Overview
API
Request a demo
API Documentation

User Service

The user service is responsible for authentication, users, groups and user plans. Services are responsible for authorization on their own resources, but typically they will check if a user is part of a certain group by resolving the user's token (see the resolveToken endpoint).

The user service supports a login and signup flow for e-mail accounts and OAuth2 providers. Currently only the Github OAuth2 provider is being used. To track which of the authentication methods is being used each User has a provider and provider ID associated with it; e.g. ("email", "[email protected]") or ("github", "41234").

The User service also support service accounts. Service accounts are owned and managed by groups and can be used to perform automated tests (most notably builds and deployments).

Endpoints

Authentication

GET
/api/v1/auth/login-methods
Retrieve the login methods supported by this server.
GET
/api/v1/auth/logout
Expire the given Escape authentication token.
GET
/api/v1/auth/signup-methods
Retrieve the signup methods supported by this server.

Authentication using Email

POST
/api/v1/auth/email/confirm
Confirm email address.
POST
/api/v1/auth/email/login
Login using email.
POST
/api/v1/auth/email/password-reset
password reset submit.
POST
/api/v1/auth/email/password-reset-request
request password reset.
POST
/api/v1/auth/email/password-strength
Check password strength.
GET
/api/v1/auth/email/resend
Resend email confirmation.
POST
/api/v1/auth/email/signup
Signup with an email address.

Authentication using OAuth2

GET
/api/v1/auth/github/callback
Callback for the Github OAuth2 flow.
GET
/api/v1/auth/github/login
Login using Github.
POST
/api/v1/auth/github/signup
Finish signup using Github.
GET
/api/v1/auth/redeem-token
Convert an OAuth redeem token to an Escape token.

Groups

GET
/api/v1/groups/
Get all groups.
POST
/api/v1/groups/
Create a new group.

Internal

GET
/
Home
POST
/api/v1/internal/add-roles-to-user
Assign roles the to a user
POST
/api/v1/internal/add-service-account
Create service account
POST
/api/v1/internal/get-groups-service-accounts
Get the service accounts in the groups.
POST
/api/v1/internal/get-groups-users
Get the users in the groups.
POST
/api/v1/internal/get-service-account-token
Get the token for a service account.
GET
/api/v1/internal/resolve-token
Resolve a Escape auth token to a user.
POST
/api/v1/internal/soft-delete-user
Soft delete a user
GET
/health
Healthcheck endpoint

Plans

GET
/api/v1/plans/
Get all plans.
POST
/api/v1/plans/
Create a new plan.
PUT
/api/v1/plans/{plan}/
Update a plan.
PUT
/api/v1/plans/{plan}/__default
Make plan the default.

Role Based Access Control

GET
/api/v1/rbac/
Get users and groups who have access; filter by GET parameters (e.g. ?project=test&build=test)
POST
/api/v1/rbac/
Set role on user or group, giving them access.
DELETE
/api/v1/rbac/
Delete access from user or group.
POST
/api/v1/rbac/converge
Set roles on user or group, giving them access.
GET
/api/v1/rbac/valid
Get valid roles for the given GET parameters (e.g. ?project=test&build=test)

Service Accounts

GET
/api/v1/teams/{team}/service-accounts/
Get service accounts
POST
/api/v1/teams/{team}/service-accounts/{username}/
Create a new service account
GET
/api/v1/teams/{team}/service-accounts/{username}/token/
Get a service account's token
DELETE
/api/v1/teams/{team}/service-accounts/{username}/token/
Cycle a service account's token

Teams

GET
/api/v1/teams/
Get all the teams the user is a member of.
POST
/api/v1/teams/
Add a team.
GET
/api/v1/teams/__typeahead
Type-ahead for teams.
GET
/api/v1/teams/{team}/
Get a team.
PUT
/api/v1/teams/{team}/
Update a team.
DELETE
/api/v1/teams/{team}/
Delete a team.
POST
/api/v1/teams/{team}/members/{username}/
Add a user to a team
DELETE
/api/v1/teams/{team}/members/{username}/
Delete user from team

Users

GET
/api/v1/users/
Get all users.
GET
/api/v1/users/__self
Get your user's profile.
GET
/api/v1/users/__typeahead
Username typeahead.
POST
/api/v1/users/{user_id}/add-to-group
GET
/api/v1/users/{username}/
Get user by username.
POST
/api/v1/users/{username}/
update user by username.
DELETE
/api/v1/users/{username}/
Admin endpoint to delete user by username.
POST
/api/v1/users/{username}/activate
Admin endpoint to activate user.
GET
/api/v1/users/{username}/avatar-image
Get avatar image by username.
POST
/api/v1/users/{username}/avatar-image
endpoint to upload image to.
POST
/api/v1/users/{username}/change-plan
Admin endpoint to change a user's plan.
POST
/api/v1/users/{username}/confirm-email
Admin endpoint to confirm user's email.

Schemas

ACLUser

Description:
Type:
object
Field Type Description Example
groups Groups
id
string
 The user ID.
is_confirmed
bool
 Whether the user has confirmed their email or not.
plan UserPlan
roles [
string
]
username
string
 The username.

AddRolesToUserRequest

Description:
Request object adding roles to user.
Type:
object
Field Type Description Example
roles
array
 The roles to assign
username
string
 Username of user to recieve roles

AddUserToGroupRequest

Description:
Request object for Add User handlers.
Type:
object
Field Type Description Example
group
string
 The group to add the user to. If the group doesn't exist it will get created.
user_id
string
 The user ID of the user to add.

AuthMethod

Description:
Type:
object
Field Type Description Example
redeem-token
string
 Only set for OAuth2 logins. Use this as the redeem code for the redeem URL.
redeem-url
string
 Only set for OAuth2 logins. The command line client uses this endpoint to fetch a valid Escape Auth Token after the User completes an successfully authenticates with an OAuth provider.
type
enum
 The type of method (one of "secret-token", "oauth")
"secret-token"
"oauth"
url
string
 The URL to use if this method were to be used.

ConvergeRoles

Description:
A team is a Group that is created and configured by a user. A team's name is not considered private information, but its user memberships and service accounts are.
Type:
object
Field Type Description Example
group
string
 Group
roles
array
 Roles
username
string
 Username

EmailConfirmationRequest

Description:
Request object for email signup handler.
Type:
object
Field Type Description Example
code
string
 The email confirmation code.

EmailLoginRequest

Description:
Request object for email login handler.
Type:
object
Field Type Description Example
email
string
 The email address
secret_token
string
 The password
username
string
 Deprecated field which is only used in place of the email field if the email field is empty. Is treated as an email address though.

EmailSignupRequest

Description:
Request object for email signup handler.
Type:
object
Field Type Description Example
email
string
 The email address
password
string
 The password
username
string
 The desired username

EscapeAuthToken

Description:
A token that can be used to authenticate to EscapeKit.
Type:
string
Example: 
"4d5cc8fe-1bf5-40c7-8ce2-9b30b81784c9"

GetGroupsServiceAccountsResponse

Description:
Response object for getGroupsServiceAccounts endpoint.
Type:
{
string
: ServiceAccount }

GetGroupsUserRequests

Description:
Request object for getGroupsUsers endpoint.
Type:
object
Field Type Description Example
groups GroupNames

GetGroupsUserResponse

Description:
Response object for getGroupsUsers endpoint keyed by group name.
Type:
{
string
: UserMap }

Group

Description:
A group is a collection of Users.
Type:
object
Example: 
{
    "description": "Internal group managed by EscapeKit.", 
    "is_internal": true, 
    "name": "my-group"
}
Field Type Description Example
description
string
 The group's description (optional)
is_internal
bool
 Internal groups are groups that are automatically created for e.g. the Inventory and State services when you create a project. They are "machine managed" and not visible to end users on their Teams page.
logo
string
 The group's logo
name
string
 The group name
role
string
 User's role within the group.

GroupName

Description:
A group name. A group groups users together. Users can have more than one group.
Type:
string
Example: 
"my-group"

GroupNameRequest

Description:
Type:
object
Field Type Description Example
name
string
 The group name. my-group

GroupNames

Description:
A list of group names.
Type:
[GroupName]

GroupRequest

Description:
Should probably be replaced with GroupNameRequest (or rather: GroupNameRequest should become GroupRequest)
Type:
object
Field Type Description Example
group
string
 The group name. my-group

Groups

Description:
Type:
[Group]
Example: 
[
    {
        "description": "Internal group managed by EscapeKit.", 
        "is_internal": true, 
        "name": "my-group"
    }, 
    {
        "description": "A team managed by some user.", 
        "is_internal": false, 
        "name": "my-team"
    }
]

LoginMethods

Description:
Map of supported login methods keyed by name.
Type:
{
string
: AuthMethod }

OAuthSignupRequest

Description:
Request object for oauth signup handler.
Type:
object
Field Type Description Example
email
string
 The email address
username
string
 The desired username

PasswordResetRequest

Description:
Request object for request password reset handler.
Type:
object
Field Type Description Example
password
string
 The password
password_reset_token
string
 The password reset token

PasswordResetRequestRequest

Description:
Request object for request password reset handler.
Type:
object
Field Type Description Example
email
string
 The email address

Permission

Description:
Type:
object
Field Type Description Example
permission
enum
 A permission. One of read, write, owner.
"read"
"write"
"owner"

RemoveUserFromGroupsRequest

Description:
Request object for Remove User from Groups handler.
Type:
object
Field Type Description Example
groups GroupNames
user_id
string
 The user ID of the user to add.

ServiceAccount

Description:
Type:
object
Field Type Description Example
name
string
team
string

ServiceAccounts

Description:
Service accounts are owned by a team and can be used to perform automated tasks. This payload contains an object mapping service account usernames to UserPermissions.
Type:
{
string
: UserPermission }

SignupMethods

Description:
Map of supported login methods keyed by name.
Type:
{
string
: AuthMethod }

SoftDeleteUserRequest

Description:
Request object soft deleting user.
Type:
object
Field Type Description Example
username
string
 Username of user to delete softly

Team

Description:
A team is a Group that is created and configured by a user. A team's name is not considered private information, but its user memberships and service accounts are.
Type:
object
Field Type Description Example
description
string
 The Team's description
logo
string
 The Team's logo
members {
string
: UserPermission } 		The team's members and their permission.
name
string
 The Team name.
permission
string
 The requesting user's permission on this Team.

TeamRequest

Description:
The request object used for team creation and team updates.
Type:
object
Field Type Description Example
description
string
 The Team's description
logo
string
 The Team's logo
name
string
 The Team name.

Teams

Description:
Teams keyed by name.
Type:
{
string
: Team }

User

Description:
Type:
object
Field Type Description Example
activated
bool
 Whether the user is activated or not.
avatar_uri
string
 URI representation of an image stored.
avatar_url
string
 A URL to a user's avatar.
description
string
 An optional user's descritpion
email
string
 The user's email address.
first_name
string
 The user's first name.
groups Groups
id
string
 The user ID.
is_confirmed
bool
 Whether the user has confirmed their email or not.
last_name
string
 The user's last name.
plan UserPlan
provider
enum
 The authentication provider.
"email"
"github"
"service-account"
provider_id
string
 The user's ID for the authentication provider.
username
string
 The username.

UserAvatarImage

Description:
Type:
object
Field Type Description Example
image_uri
string
 The string representation of the image.

UserID

Description:
A user ID.
Type:
string

UserMap

Description:
The user ID keyed by username.
Type:
{
string
: UserID }

UserPermission

Description:
A user's permission on a particular resource.
Type:
object
Field Type Description Example
id
string
 The User's ID.
permission
string
 The User's permission on the resource.
username
string
 The User's name

UserPlan

Description:
A user plan provides some controls over what a user is allowed to do on the platform.
Type:
object
Field Type Description Example
can_create_state_project
bool
 Is the user allowed to create State projects?
can_create_team
bool
 Is the user allowed to create Teams?
can_manage_project_acl
bool
 Is the user allowed to modify ACLs on Inventory projects?
can_manage_project_hooks
bool
 Is the user allowed to modify hooks on Inventory projects?
name
string
 The name of the plan.
project_limit
int
 The number of projects the user is allowed to create.

UserPlanName

Description:
Type:
object
Field Type Description Example
name
string
 The name of the plan.

UserPlans

Description:
Type:
object
Field Type Description Example
default_plan
string
 The default plan.
plans {
string
: UserPlan } 		A map with UserPlans keyed by the plan's name.

Users

Description:
Type:
[User]