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).

Authentication

GET

/api/v1/auth/login-methods

Retrieve the login methods supported by this server.

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200	LoginMethods

GET

/api/v1/auth/logout

Expire the given Escape authentication token.

Authentication:

User has to be logged in.

Responses:

Status	Response Type	Description
200		Empty response

GET

/api/v1/auth/signup-methods

Retrieve the signup methods supported by this server.

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200	SignupMethods
500		Signup disabled.

Authentication using Email

POST

/api/v1/auth/email/confirm

Confirm email address.

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200		Empty response. User successfully confirmed.
400		Invalid JSON body.
404		Confirmation code not found.

POST

/api/v1/auth/email/login

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200		Empty response. Successfully logged in. The X-Escape-Token cookie and header will both be set to a valid Escape Auth Token.
400		Invalid JSON body.
401		Wrong user and password combination.

POST

/api/v1/auth/email/password-reset

password reset submit.

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200		Empty response. Request received.
400		Invalid JSON body.

POST

/api/v1/auth/email/password-reset-request

request password reset.

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200		Empty response. Request received.
400		Invalid JSON body.

POST

/api/v1/auth/email/password-strength

Check password strength.

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200	User	Payload describes quality of password provided

GET

/api/v1/auth/email/resend

Resend email confirmation.

Authentication:

Unknown ACL: acl.UnconfirmedUserACL

Responses:

Status	Response Type	Description
500		Server error. Probably an error in the communication between the user service and the notification service.

POST

/api/v1/auth/email/signup

Signup with an email address.

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200	User	Signup successful. Returns created user.
400		There was a problem with the request. Missing or invalid username; missing or weak password.
409		The user already exists.
500		Server error. Most likely signup is disabled.

Authentication using OAuth2

GET

/api/v1/auth/github/callback

Callback for the Github OAuth2 flow.

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200		Empty response. Successfully logged in.
302		Redirect to complete OAuth flow or to use the redirect_url parameter set during login.
400		Missing redeem-token parameter.
404		Redeem token not found.
500		Server side error. Possibly an error in the OAuth flow or session management.

GET

/api/v1/auth/github/login

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200		Empty response. Successfully logged in.
302		Redirect to complete OAuth flow, to use redirect_url parameter or to go to /app/signup if signups are disabled.
400		Missing redeem-token parameter.
404		Redeem token not found.
500		Server side error. Possibly an error in the OAuth flow or session management.

POST

/api/v1/auth/github/signup

Finish signup using Github.

Authentication:

User has to be logged in, but the account doesn't need to be confirmed.

Responses:

Status	Response Type	Description
200	User
400		User error. User acccount is not managed by the "github" provider, invalid JSON body, username or email invalid.
404		User not found.
500		Server side error. Possibly an error in the OAuth flow, session management or signups might be disabled altogether.

GET

/api/v1/auth/redeem-token

Convert an OAuth redeem token to an Escape token.

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200	EscapeAuthToken
400		Missing redeem-token parameter.
404		Redeem token not found.

Groups

GET

/api/v1/groups/

Get all groups.

Authentication:

Admins only.

Responses:

Status	Response Type	Description
200	Groups	Groups payload

POST

/api/v1/groups/

Create a new group.

Authentication:

Admins only.

Responses:

Status	Response Type	Description
200		Empty response.

Internal

GET

Home

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200		The version of the user service

POST

/api/v1/internal/add-roles-to-user

Assign roles the to a user

Authentication:

This is a public endpoint

POST

/api/v1/internal/add-service-account

Create service account

Authentication:

This is a public endpoint

POST

/api/v1/internal/get-groups-service-accounts

Get the service accounts in the groups.

Description:

Does a combined query for the given groups to find out what service accounters are members of it. The group does not necessarily have to exist.

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200	GetGroupsServiceAccountsResponse

POST

/api/v1/internal/get-groups-users

Get the users in the groups.

Description:

Does a combined query for the given groups to find out what users are members of it. The group does not necessarily have to exist.

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200	GetGroupsUserResponse

POST

/api/v1/internal/get-service-account-token

Get the token for a service account.

Authentication:

This is a public endpoint

GET

/api/v1/internal/resolve-token

Resolve a Escape auth token to a user.

Description:

Internal service endpoint used for other services to resolve Escape authentication tokens to Users. Mainly used to implement ACLs.

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200	ACLUser
401		Invalid token.

POST

/api/v1/internal/soft-delete-user

Soft delete a user

Authentication:

This is a public endpoint

GET

/health

Healthcheck endpoint

Authentication:

This is a public endpoint

Responses:

Status	Response Type	Description
200		The version of the user service

Plans

GET

/api/v1/plans/

Get all plans.

Description:

Administrator endpoint to list all the defined plans.

Authentication:

Admins only.

Responses:

Status	Response Type	Description
200	UserPlans	Plans payload

POST

/api/v1/plans/

Create a new plan.

Description:

Administrator endpoint to create a new plan.

Authentication:

Admins only.

Responses:

Status	Response Type	Description
200		Empty response.
400		Failed to read JSON body
409		A plan with this name already exists

PUT

/api/v1/plans/{plan}/

Update a plan.

Description:

Administrator endpoint to update an existing plan.

Authentication:

Admins only.

Parameters:

/{plan}/

string

Responses:

Status	Response Type	Description
200		Empty response.
400		Failed to read JSON body
404		A plan with this name could not be found

PUT

/api/v1/plans/{plan}/__default

Make plan the default.

Description:

Administrator endpoint to set the default plan.

Authentication:

Admins only.

Parameters:

/{plan}/

string

Responses:

Status	Response Type	Description
200		Empty response.
404		A plan with this name could not be found

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)

Authentication:

User has to be logged in.

Responses:

Status	Response Type	Description
200		Roles

POST

/api/v1/rbac/

Set role on user or group, giving them access.

Authentication:

User has to be logged in.

Responses:

Status	Response Type	Description
200		Roles

DELETE

/api/v1/rbac/

Delete access from user or group.

Authentication:

User has to be logged in.

Responses:

Status	Response Type	Description
200		Roles

POST

/api/v1/rbac/converge

Set roles on user or group, giving them access.

Authentication:

User has to be logged in.

Responses:

Status	Response Type	Description
200		Roles

GET

/api/v1/rbac/valid

Get valid roles for the given GET parameters (e.g. ?project=test&build=test)

Authentication:

User has to be logged in.

Responses:

Status	Response Type	Description
200		Roles

Service Accounts

GET

/api/v1/teams/{team}/service-accounts/

Get service accounts

Description:

Get the team's service accounts. Only team mebers and administrators can view this.

Authentication:

User has to be a member of the team {team}

Parameters:

/{team}/

string

The team name.

Responses:

Status	Response Type	Description
200	ServiceAccounts

POST

/api/v1/teams/{team}/service-accounts/{username}/

Create a new service account

Description:

Create a new service account. Only team owners and administrators can perform this action.

Authentication:

User has to be an owner of the team {team}

Parameters:

/{team}/		string	The team this service account is part of.
/{username}/		string	The username of the new service account

Responses:

Status	Response Type	Description
200		Empty response.

GET

/api/v1/teams/{team}/service-accounts/{username}/token/

Get a service account's token

Description:

Retrieve the account token for a service account. Only team members and administrators are able to view this.

Authentication:

User has to be a member of the team {team}

Parameters:

/{team}/		string	The team this service account is part of.
/{username}/		string	The username of the service account

Responses:

Status	Response Type	Description
200	EscapeAuthToken

DELETE

/api/v1/teams/{team}/service-accounts/{username}/token/

Cycle a service account's token

Description:

Invalidate and delete the old service account token and generate a new one. Only team owners and administrators can perform this action.

Authentication:

User has to be an owner of the team {team}

Parameters:

/{team}/		string	The team this service account is part of.
/{username}/		string	The username of the service account

Responses:

Status	Response Type	Description
200	EscapeAuthToken

Teams

GET

/api/v1/teams/

Get all the teams the user is a member of.

Description:

Get all the teams the requesting user is part of. Administrators are able to see all the teams.

Authentication:

User has to be logged in.

Responses:

Status	Response Type	Description
200	Teams	Teams payload

POST

/api/v1/teams/

Add a team.

Description:

Create a new team. The user's plan controls whether or not this operation is allowed to succeed.

Authentication:

User has to be logged in.

Responses:

Status	Response Type	Description
200		Empty response.
400		Invalid request. Most likely caused by a missing or invalid team name.
401		The user is not allowed to create plans, because their Plan does not allow it.
409		The team name already exists.

GET

/api/v1/teams/__typeahead

Type-ahead for teams.

Description:

Type-ahead for team names. Also returns teams that the user might not be part of.

Authentication:

User has to be logged in.

Parameters:

/{team}/		string	The team name.
?query=		string

Responses:

Status	Response Type	Description
200	Teams	Teams payload

GET

/api/v1/teams/{team}/

Get a team.

Description:

Get a team's details. Only allowed for team members and administrators.

Authentication:

User has to be a member of the team {team}

Parameters:

/{team}/

string

The team name.

Responses:

Status	Response Type	Description
200	Team	Teams payload
401		The user is not logged in and is not allowed to see this team.
403		The user is not allowed to see this team.
404		The team could not be found or the team is actually an internal Group.

PUT

/api/v1/teams/{team}/

Update a team.

Description:

Update a team's description and logo.

Authentication:

User has to be an owner of the team {team}

Parameters:

/{team}/

string

The team name.

Responses:

Status	Response Type	Description
200		Empty response.
401		The user is not logged in and is not allowed to update this team.
403		The user is not allowed to update this team.
404		The team could not be found or the team is actually an internal Group.

DELETE

/api/v1/teams/{team}/

Delete a team.

Description:

Delete a team and its memberships.

Authentication:

User has to be an owner of the team {team}

Parameters:

/{team}/

string

The team name.

Responses:

Status	Response Type	Description
200		Empty response.
401		The user is not logged in and is not allowed to delete this team.
403		The user is not allowed to delete this team.
404		The team could not be found or the team is actually an internal Group.

POST

/api/v1/teams/{team}/members/{username}/

Add a user to a team

Authentication:

User has to be an owner of the team {team}

Parameters:

/{team}/		string	The team name.
/{username}/		string	The username to add.

Responses:

Status	Response Type	Description
200		Empty response.
400		There was a problem with the request. Most like the permission was missing or invalid.
401		The user is not logged in and is not allowed to configure this team.
403		The user is not allowed to configure this team.
404		The team could not be found or the team is actually an internal Group.

DELETE

/api/v1/teams/{team}/members/{username}/

Delete user from team

Authentication:

User has to be an owner of the team {team}

Parameters:

/{team}/		string	The team name.
/{username}/		string	The username to add.

Responses:

Status	Response Type	Description
200		Empty response.
400		There was a problem with the request. Most like the permission was missing or invalid.
401		The user is not logged in and is not allowed to configure this team.
403		The user is not allowed to configure this team.
404		The team could not be found or the team is actually an internal Group.

Users

GET

/api/v1/users/

Get all users.

Authentication:

Admins only.

Responses:

Status	Response Type	Description
200	Users	Users payload

GET

/api/v1/users/__self

Get your user's profile.

Authentication:

User has to be logged in, but the account doesn't need to be confirmed.

Responses:

Status	Response Type	Description
200	User	User payload

GET

/api/v1/users/__typeahead

Username typeahead.

Authentication:

User has to be logged in.

Parameters:

?query=

string

Responses:

Status	Response Type	Description
200	object	User payload

POST

/api/v1/users/{user_id}/add-to-group

Description:

Admin endpoint to add user to a group. Doesn't create the group if it doesn't exist. NB. the user is referenced by its ID!

Authentication:

Admins only.

Parameters:

/{user_id}/

string

Responses:

Status	Response Type	Description
200		Empty response.

GET

/api/v1/users/{username}/

Get user by username.

Authentication:

User has to be logged in.

Parameters:

/{username}/

string

Responses:

Status	Response Type	Description
200	User	User payload

POST

/api/v1/users/{username}/

update user by username.

Authentication:

User has to be logged in.

Parameters:

/{username}/

string

Responses:

Status	Response Type	Description
200		Empty response.

DELETE

/api/v1/users/{username}/

Admin endpoint to delete user by username.

Authentication:

Admins only.

Parameters:

/{username}/

string

Responses:

Status	Response Type	Description
200		Empty response.

POST

/api/v1/users/{username}/activate

Admin endpoint to activate user.

Authentication:

Admins only.

Parameters:

/{username}/

string

Responses:

Status	Response Type	Description
200		Empty response.

GET

/api/v1/users/{username}/avatar-image

Get avatar image by username.

Authentication:

User has to be logged in.

Parameters:

/{username}/

string

Responses:

Status	Response Type	Description
200	User	User's avatar image

POST

/api/v1/users/{username}/avatar-image

endpoint to upload image to.

Authentication:

User has to be logged in.

Parameters:

/{username}/

string

Responses:

Status	Response Type	Description
200		Empty response.

POST

/api/v1/users/{username}/change-plan

Admin endpoint to change a user's plan.

Authentication:

Admins only.

Parameters:

/{username}/

string

Responses:

Status	Response Type	Description
200		Empty response.

POST

/api/v1/users/{username}/confirm-email

Admin endpoint to confirm user's email.

Authentication:

Admins only.

Parameters:

/{username}/

string

Responses:

Status	Response Type	Description
200		Empty response.

Schemas

ACLUser
AddRolesToUserRequest
AddUserToGroupRequest
AuthMethod
ConvergeRoles
EmailConfirmationRequest
EmailLoginRequest
EmailSignupRequest
EscapeAuthToken
GetGroupsServiceAccountsResponse
GetGroupsUserRequests
GetGroupsUserResponse
Group
GroupName
GroupNameRequest
GroupNames
GroupRequest
Groups
LoginMethods
OAuthSignupRequest
PasswordResetRequest
PasswordResetRequestRequest
Permission
RemoveUserFromGroupsRequest
ServiceAccount
ServiceAccounts
SignupMethods
SoftDeleteUserRequest
Team
TeamRequest
Teams
User
UserAvatarImage
UserID
UserMap
UserPermission
UserPlan
UserPlanName
UserPlans
Users

ACLUser

Description:

Type:

object

Field	Type	Description
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
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
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
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
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
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
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
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
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]

Escape

EscapeKit

Escape

EscapeKit

API Documentation

User Service

Endpoints

Authentication

Authentication using Email

Authentication using OAuth2

Groups

Internal

Plans

Role Based Access Control

Service Accounts

Teams

Users

Schemas

ACLUser

AddRolesToUserRequest

AddUserToGroupRequest

AuthMethod

ConvergeRoles

EmailConfirmationRequest

EmailLoginRequest

EmailSignupRequest

EscapeAuthToken

GetGroupsServiceAccountsResponse

GetGroupsUserRequests

GetGroupsUserResponse

Group

GroupName

GroupNameRequest

GroupNames

GroupRequest

Groups

LoginMethods

OAuthSignupRequest

PasswordResetRequest

PasswordResetRequestRequest

Permission

RemoveUserFromGroupsRequest

ServiceAccount

ServiceAccounts

SignupMethods

SoftDeleteUserRequest

Team

TeamRequest

Teams

User

UserAvatarImage

UserID

UserMap

UserPermission

UserPlan

UserPlanName

UserPlans

Users