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", "test@example.com") 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

/api/v1/auth/email/confirm
Confirm email address.
/api/v1/auth/email/login
Login using email.
/api/v1/auth/email/password-reset
password reset submit.
/api/v1/auth/email/password-reset-request
request password reset.
/api/v1/auth/email/password-strength
Check password strength.
GET
/api/v1/auth/email/resend
Resend email confirmation.
/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.
/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.
/api/v1/groups/
Create a new group.

Internal

GET
/
Home
/api/v1/internal/add-roles-to-user
Assign roles the to a user
/api/v1/internal/add-service-account
Create service account
/api/v1/internal/get-groups-service-accounts
Get the service accounts in the groups.
/api/v1/internal/get-groups-users
Get the users in the groups.
/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.
/api/v1/internal/soft-delete-user
Soft delete a user
GET
/health
Healthcheck endpoint

Plans

GET
/api/v1/plans/
Get all plans.
/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)
/api/v1/rbac/
Set role on user or group, giving them access.
DELETE
/api/v1/rbac/
Delete access from user or group.
/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
/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.
/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.
/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.
/api/v1/users/{user_id}/add-to-group
GET
/api/v1/users/{username}/
Get user by username.
/api/v1/users/{username}/
update user by username.
DELETE
/api/v1/users/{username}/
Admin endpoint to delete user by username.
/api/v1/users/{username}/activate
Admin endpoint to activate user.
GET
/api/v1/users/{username}/avatar-image
Get avatar image by username.
/api/v1/users/{username}/avatar-image
endpoint to upload image to.
/api/v1/users/{username}/change-plan
Admin endpoint to change a user's plan.
/api/v1/users/{username}/confirm-email
Admin endpoint to confirm user's email.

Schemas

ACLUser

Description:
Type:
object
FieldTypeDescriptionExample
groupsGroups
id
string
The user ID.
is_confirmed
bool
Whether the user has confirmed their email or not.
planUserPlan
roles[
string
]
username
string
The username.

AddRolesToUserRequest

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

AddUserToGroupRequest

Description:
Request object for Add User handlers.
Type:
object
FieldTypeDescriptionExample
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
FieldTypeDescriptionExample
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
FieldTypeDescriptionExample
group
string
Group
roles
array
Roles
username
string
Username

EmailConfirmationRequest

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

EmailLoginRequest

Description:
Request object for email login handler.
Type:
object
FieldTypeDescriptionExample
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
FieldTypeDescriptionExample
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
FieldTypeDescriptionExample
groupsGroupNames

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"
}
FieldTypeDescriptionExample
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
FieldTypeDescriptionExample
name
string
The group name.my-group

GroupNames

Description:
A list of group names.
Type:

GroupRequest

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

Groups

Description:
Type:
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
FieldTypeDescriptionExample
email
string
The email address
username
string
The desired username

PasswordResetRequest

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

PasswordResetRequestRequest

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

Permission

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

RemoveUserFromGroupsRequest

Description:
Request object for Remove User from Groups handler.
Type:
object
FieldTypeDescriptionExample
groupsGroupNames
user_id
string
The user ID of the user to add.

ServiceAccount

Description:
Type:
object
FieldTypeDescriptionExample
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
FieldTypeDescriptionExample
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
FieldTypeDescriptionExample
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
FieldTypeDescriptionExample
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
FieldTypeDescriptionExample
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.
groupsGroups
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.
planUserPlan
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
FieldTypeDescriptionExample
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
FieldTypeDescriptionExample
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
FieldTypeDescriptionExample
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
FieldTypeDescriptionExample
name
string
The name of the plan.

UserPlans

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

Users

Description:
Type: