Access Management

Description

In order to support any kind of multi-tenancy and manage access to different parts of the coldwave API this module has been created.

When this module is enabled, most API endpoints need a specific token to be supplied with the HTTP Authorization header. Users who already have an account can request a token via the token endpoint. This endpoint will return a token which can be used for HTTP requests as described above. The token by default has a lifetime of one hour.

TIP

The json-web-token is signed by the server. You can verify the token yourself by validating the signature. Use the public key from the well-known endpoint.

A token contains all the information about the user's permissions. This information is divided into two parts: One being the actual permission that is required to call this endpoint, and the other is the resource you want to access. Refer to the Access paragraph for each specific request in the API section of each module.. If there is no access paragraph present, anyone can access this endpoint.

TIP

The permission parameter tries to stick to theCRUD-paradigm. You can therefore expect create, read, update and delete permissions. If you want to grant access to any available resources (e.g for super admins) use the wildcard character * that matches any resource.

WARNING

The backend generates a key pair on server restart. This is done, so the server can work without a database, with the positive side effect that a database breach will not result in losing the private key.

Device and Service Identifier

The token furthermore includes information about service and device identifiers. Those identifiers are used to filter access on a per IoT-device level. In short, devices connecting to the coldwave backend can create zero or more services (instances of a specific object) which might not be accessible by every user. As an example: Maybe every user in your system needs access to the history of the temperature-property from a thermostat, but only for the specific device at his workplace. While access to the history will be handled by the permission and resource part of the json-web-token, the actual device mapping will be handled by the device identifier entry in the token.

TIP

Using the wildcard character * will grant access to all service- and device-identifiers.

Hierarchy

The hierarchy within the application is split into three parts:

• Groups
• Roles
• User

Each user belongs to a single group and has a single role. Every role belongs to a single group. All the entities above allow setting device- as well as service-identifiers. When generating a token, the backend traverses the path from user to role to group to check for any matching identifier. The first matching identifier will be added to the returned token from the token endpoint. This allows for a fine-grained access control.

Groups

A group within the coldwave application is a collection of roles and users. This can be used to create a container for organizations or companies. Most recent use-cases only use one single group as their root structure. However, opening up to third-party users could require the creation of multiple groups to better manage devices, services, permissions or accounts.

Roles

The roles contain the actual permissions a user has. There can be multiple roles within a group to grant or deny access to different consumers while each user has only one role and group. The roles are not required to have device- and service identifiers. If they are present they will be added to the token.

User

A user represents a single account. Again, a user belongs to a single role, which grants him permission to access resources and in turn belongs to a single group. While all three, users, roles and groups, can have properties that grant or deny access based on service or device identifiers, only the group is required to have such an entry (can be *).

Creating Accounts

First Account

When starting the backend for the first time, there are multiple ways to create the first account. This account needs to be set up in order to actually use the backend properly, otherwise you do not have access to the application interface. When using a database and control over the MongoDB is granted, simply add three entries in three collections, those being:

1. Collection groups

const group = {
    _id:"group-name", // The name of the group
    name:"group-name", 
    serviceIdentifier:"*", // Either a wildcard or a list of service identifiers
    deviceIdentifier:"*" // Either a wildcard or a list of device identifiers
}

2. Collection roles

const role = {
    _id:"role-name", // The name of the role
    name:"role-name", 
    group: "group-name", // The id of the group set earlier
    access: [{
        actions: ["create", "read", "update", "delete"],
        resource: "*"
    }]
    // serviceIdentifier:"*", < Optional. A list of service identifiers
    // deviceIdentifier:"*" < Optional. A list of device identifiers
}

3. Collection users

const user = {
    _id:"user-name", // The name of the group
    group:"group-name",
    role: "role-name",
    hash: "hash", // See details below for more information
    salt: "salt", // See details below for more information
    // serviceIdentifier:"*", < Optional. A list of service identifiers
    // deviceIdentifier:"*" < Optional. A list of device identifiers
}

Details

The function used for the hash is the asynchronous password-based key derivation function scrypt with a key-length of 64. The salt are 16 random bytes encoded in hex-format.

TIP

This setup above will create an admin account with access to everything.

The approach above requires a database. However, the identity access management module can be used without a database. Simply provide a initialAccount to the configuration-file You can set up an account that will be added to the cache each time the application (re-)starts. If there is a database connection this account will also be written into the database.

Creating a user

Once a group and a role have been created, it is possible to add users. By calling the create-user endpoint, the backend returns an invitation-code that can be forwarded to the user, who in turn can add a password to their account. This is done with a request at the sign-up endpoint. This concludes the user creation and sign-up.

Events

Following events are transmitted via the websocket.

IAM_KEY_ADD

IAM_KEY_UPDATE

IAM_KEY_DELETE

IAM_GROUP_ADD

IAM_GROUP_DELETE

IAM_GROUP_UPDATE

IAM_ROLE_ADD

IAM_ROLE_DELETE

IAM_ROLE_UPDATE

IAM_USER_CREATE

IAM_USER_SIGNUP

IAM_USER_UPDATE

IAM_USER_DELETE

IAM_USER_CODE_TIMEOUT

IAM_USER_CREATE_EXTERNAL

IAM_USER_RESET

This event will be generated when a new API key is generated. The hash field is omitted. This event requires read access to the resource iam.keys.

Name	Description
type stringconstant	Constant value: IAM_KEY_ADD
expiresAt number	The timestamp the key will expire at.
group string	The name for a group between 3 and 30 characters.
prefix string	The prefix the key will be identifier at.
role string	The name for a role between 3 and 30 characters.

API

Endpoints

POST

Create Group

GET

List Groups

GET

Get Group

PATCH

Update Group

DEL

Delete single Group

POST

Create Role

GET

List Roles

GET

Get Role

PATCH

Update Role

DEL

Delete single Role

POST

Create User

POST

Sign Up

GET

List User

PATCH

Change Password

GET

Get User

PATCH

Update a single user

POST

Reset User

DEL

Delete User

POST

Create API Key

GET

List all API Keys

DEL

Delete all API Keys

GET

Get API Key

PATCH

Update API Key

DEL

Delete API Key

POST

Add Pairing

GET

List Pairings

DEL

Delete Pairing

POST

Add Single Pairing

GET

Get Single Pairing

DEL

Delete Single Pairing

GET

Get Token Information

GET

Get Token

POST

Use Refresh Token

GET

Well-Known Information

GET

Authorization Code Callback

POST

Enable two factor authentication

POST

Verify two factor authentication

POST

Disable two factor authentication

POST

Request token with 2FA

POST

Add Pairing (Deprecated)

GET

List Pairings (Deprecated)

DEL

Delete Pairing (Deprecated)

Create Group

Creates a new group if it does not already exists.

POST

/api/v1/iam/groups

Access

This endpoint requires create permission for the resource iam.groups.

Request Body

Name	Description
name string	The group name.
serviceIdentifier	Either a list of service identifier that belong to the group this field was used at or the wildcard character `*` that will match any service identifier.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier	Either a list of device identifier that belong to the group this field was used at or the wildcard character `*` that will match any device identifier.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

List Groups

List all groups. Depending on the depth, get more information regarding roles and users.

GET

/api/v1/iam/groups

Access

This endpoint requires read permission for the resource iam.groups.

Query Parameter

Name	Description
depth integeroptional	Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for.

Response

Name	Description
name string	The group name.
serviceIdentifier	Either a list of service identifier that belong to the group this field was used at or the wildcard character `*` that will match any service identifier.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier	Either a list of device identifier that belong to the group this field was used at or the wildcard character `*` that will match any device identifier.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
roles arrayoptional	The roles for that group are returned when using a high enough value for the query parameter `depth`.
roles.[ ].access arrayoptional	An array containing information about what can be accessed. Default: []
roles.[ ].access.[ ].resource string	The resource the access is referring to. The access required to call an API can be gathered from the access part of every API definition. The resource literal * will match any resource.
roles.[ ].access.[ ].actions arraystring	The actions that the entity can issue on the resource. Most commonly are: create, read, update, delete.
roles.[ ].serviceIdentifier optional	Either a list of service identifier that belong to the role this field was used at or the wildcard character `*` that will match any service identifier.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
roles.[ ].deviceIdentifier optional	Either a list of device identifier that belong to the role this field was used at or the wildcard character `*` that will match any device identifier.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
roles.[ ].name string	The name of the role.
roles.[ ].group string	The name of the group the role belongs to.
roles.[ ].users arrayoptional	The user for that role are returned when using a high enough value for the query parameter `depth`.
roles.[ ].users.[ ].group string	The group for the given user.
roles.[ ].users.[ ].role string	The role for the given user.
roles.[ ].users.[ ].name string	The user name.
roles.[ ].users.[ ].code stringoptional	The code is available within the sign up process. If a user was created and has yet to sign up, the code is available until it expires. See `expiresAt` for more information.
roles.[ ].users.[ ].expiresAt integeroptional	The UTC timestamp at which the sign up process can no longer be completed and the user will be deleted automatically.
roles.[ ].users.[ ].external booleanoptional	Set to true if a user is from an external oauth provider. The reset function is permitted for external user.
roles.[ ].users.[ ].serviceIdentifier optional	Either a list of service identifier that belong to the user or the wildcard character `*` that will match any service identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
roles.[ ].users.[ ].deviceIdentifier optional	Either a list of device identifier that belong to the user or the wildcard character `*` that will match any device identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
roles.[ ].users.[ ].twoFactorStatus stringoptionalenum	The current two factor authentication status. Possible values: ENABLED, PENDING, DISABLED
roles.[ ].keys arrayoptional	The API keys for that role are returned when using a high enough value for the query parameter `depth`.
roles.[ ].keys.[ ].expiresAt number	The timestamp the key will expire at.
roles.[ ].keys.[ ].group string	The name for a group between 3 and 30 characters.
roles.[ ].keys.[ ].prefix string	The prefix the key will be identifier at.
roles.[ ].keys.[ ].role string	The name for a role between 3 and 30 characters.

Get Group

To view a single group use this endpoint. Depending on the depth, more information can be acquired directly.

GET

/api/v1/iam/groups/:groupName

Access

This endpoint requires read permission for the resource iam.groups.

URL Parameter

Name	Description
groupName string	The group name

Query Parameter

Name	Description
depth integeroptional	Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for.

Response

Name	Description
name string	The group name.
serviceIdentifier	Either a list of service identifier that belong to the group this field was used at or the wildcard character `*` that will match any service identifier.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier	Either a list of device identifier that belong to the group this field was used at or the wildcard character `*` that will match any device identifier.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
roles arrayoptional	The roles for that group are returned when using a high enough value for the query parameter `depth`.
roles.[ ].access arrayoptional	An array containing information about what can be accessed. Default: []
roles.[ ].access.[ ].resource string	The resource the access is referring to. The access required to call an API can be gathered from the access part of every API definition. The resource literal * will match any resource.
roles.[ ].access.[ ].actions arraystring	The actions that the entity can issue on the resource. Most commonly are: create, read, update, delete.
roles.[ ].serviceIdentifier optional	Either a list of service identifier that belong to the role this field was used at or the wildcard character `*` that will match any service identifier.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
roles.[ ].deviceIdentifier optional	Either a list of device identifier that belong to the role this field was used at or the wildcard character `*` that will match any device identifier.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
roles.[ ].name string	The name of the role.
roles.[ ].group string	The name of the group the role belongs to.
roles.[ ].users arrayoptional	The user for that role are returned when using a high enough value for the query parameter `depth`.
roles.[ ].users.[ ].group string	The group for the given user.
roles.[ ].users.[ ].role string	The role for the given user.
roles.[ ].users.[ ].name string	The user name.
roles.[ ].users.[ ].code stringoptional	The code is available within the sign up process. If a user was created and has yet to sign up, the code is available until it expires. See `expiresAt` for more information.
roles.[ ].users.[ ].expiresAt integeroptional	The UTC timestamp at which the sign up process can no longer be completed and the user will be deleted automatically.
roles.[ ].users.[ ].external booleanoptional	Set to true if a user is from an external oauth provider. The reset function is permitted for external user.
roles.[ ].users.[ ].serviceIdentifier optional	Either a list of service identifier that belong to the user or the wildcard character `*` that will match any service identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
roles.[ ].users.[ ].deviceIdentifier optional	Either a list of device identifier that belong to the user or the wildcard character `*` that will match any device identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
roles.[ ].users.[ ].twoFactorStatus stringoptionalenum	The current two factor authentication status. Possible values: ENABLED, PENDING, DISABLED
roles.[ ].keys arrayoptional	The API keys for that role are returned when using a high enough value for the query parameter `depth`.
roles.[ ].keys.[ ].expiresAt number	The timestamp the key will expire at.
roles.[ ].keys.[ ].group string	The name for a group between 3 and 30 characters.
roles.[ ].keys.[ ].prefix string	The prefix the key will be identifier at.
roles.[ ].keys.[ ].role string	The name for a role between 3 and 30 characters.

Update Group

To update a single group use this endpoint.

PATCH

/api/v1/iam/groups/:groupName

Access

This endpoint requires update permission for the resource iam.groups.

URL Parameter

Name	Description
groupName string	The group name

Request Body

Name	Description
serviceIdentifier optional	Either a list of service identifier that belong to the group this field was used at or the wildcard character `*` that will match any service identifier.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier optional	Either a list of device identifier that belong to the group this field was used at or the wildcard character `*` that will match any device identifier.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Delete single Group

Calling this endpoint will delete the group and all other resources belonging to that group such as roles, users and API keys.

DELETE

/api/v1/iam/groups/:groupName

Access

This endpoint requires delete permission for the resource iam.groups.

URL Parameter

Name	Description
groupName string	The group name

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Create Role

Creates a new role if it does not already exists.

POST

/api/v1/iam/groups/:groupName/roles

Access

This endpoint requires create permission for the resource iam.roles.

URL Parameter

Name	Description
groupName string	The group name

Request Body

Name	Description
access arrayoptional	An array containing information about what can be accessed. Default: []
access.[ ].resource string	The resource the access is referring to. The access required to call an API can be gathered from the access part of every API definition. The resource literal * will match any resource.
access.[ ].actions arraystring	The actions that the entity can issue on the resource. Most commonly are: create, read, update, delete.
serviceIdentifier optional	Either a list of service identifier that belong to the role this field was used at or the wildcard character `*` that will match any service identifier.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier optional	Either a list of device identifier that belong to the role this field was used at or the wildcard character `*` that will match any device identifier.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
name string	The name of the role.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

List Roles

List all roles. Depending on the depth, get more information regarding users and API keys.

GET

/api/v1/iam/groups/:groupName/roles

Access

This endpoint requires create permission for the resource iam.roles.

URL Parameter

Name	Description
groupName string	The group name

Query Parameter

Name	Description
depth integeroptional	Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for.

Response

Name	Description
access arrayoptional	An array containing information about what can be accessed. Default: []
access.[ ].resource string	The resource the access is referring to. The access required to call an API can be gathered from the access part of every API definition. The resource literal * will match any resource.
access.[ ].actions arraystring	The actions that the entity can issue on the resource. Most commonly are: create, read, update, delete.
serviceIdentifier optional	Either a list of service identifier that belong to the role this field was used at or the wildcard character `*` that will match any service identifier.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier optional	Either a list of device identifier that belong to the role this field was used at or the wildcard character `*` that will match any device identifier.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
name string	The name of the role.
group string	The name of the group the role belongs to.
users arrayoptional	The user for that role are returned when using a high enough value for the query parameter `depth`.
users.[ ].group string	The group for the given user.
users.[ ].role string	The role for the given user.
users.[ ].name string	The user name.
users.[ ].code stringoptional	The code is available within the sign up process. If a user was created and has yet to sign up, the code is available until it expires. See `expiresAt` for more information.
users.[ ].expiresAt integeroptional	The UTC timestamp at which the sign up process can no longer be completed and the user will be deleted automatically.
users.[ ].external booleanoptional	Set to true if a user is from an external oauth provider. The reset function is permitted for external user.
users.[ ].serviceIdentifier optional	Either a list of service identifier that belong to the user or the wildcard character `*` that will match any service identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
users.[ ].deviceIdentifier optional	Either a list of device identifier that belong to the user or the wildcard character `*` that will match any device identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
users.[ ].twoFactorStatus stringoptionalenum	The current two factor authentication status. Possible values: ENABLED, PENDING, DISABLED
keys arrayoptional	The API keys for that role are returned when using a high enough value for the query parameter `depth`.
keys.[ ].expiresAt number	The timestamp the key will expire at.
keys.[ ].group string	The name for a group between 3 and 30 characters.
keys.[ ].prefix string	The prefix the key will be identifier at.
keys.[ ].role string	The name for a role between 3 and 30 characters.

Get Role

To view a single role use this endpoint. Depending on the depth, more information can be acquired directly.

GET

/api/v1/iam/groups/:groupName/roles/:roleName

Access

This endpoint requires read permission for the resource iam.roles.

URL Parameter

Name	Description
groupName string	The group name for the role.
roleName string	The name for the role.

Query Parameter

Name	Description
depth integeroptional	Due to the fact that some resources follow certain hierarchies, the depth query parameter can be used to include nested information in the response. This can be used to minimize roundtrips and is generally advised for.

Response

Name	Description
access arrayoptional	An array containing information about what can be accessed. Default: []
access.[ ].resource string	The resource the access is referring to. The access required to call an API can be gathered from the access part of every API definition. The resource literal * will match any resource.
access.[ ].actions arraystring	The actions that the entity can issue on the resource. Most commonly are: create, read, update, delete.
serviceIdentifier optional	Either a list of service identifier that belong to the role this field was used at or the wildcard character `*` that will match any service identifier.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier optional	Either a list of device identifier that belong to the role this field was used at or the wildcard character `*` that will match any device identifier.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
name string	The name of the role.
group string	The name of the group the role belongs to.
users arrayoptional	The user for that role are returned when using a high enough value for the query parameter `depth`.
users.[ ].group string	The group for the given user.
users.[ ].role string	The role for the given user.
users.[ ].name string	The user name.
users.[ ].code stringoptional	The code is available within the sign up process. If a user was created and has yet to sign up, the code is available until it expires. See `expiresAt` for more information.
users.[ ].expiresAt integeroptional	The UTC timestamp at which the sign up process can no longer be completed and the user will be deleted automatically.
users.[ ].external booleanoptional	Set to true if a user is from an external oauth provider. The reset function is permitted for external user.
users.[ ].serviceIdentifier optional	Either a list of service identifier that belong to the user or the wildcard character `*` that will match any service identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
users.[ ].deviceIdentifier optional	Either a list of device identifier that belong to the user or the wildcard character `*` that will match any device identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
users.[ ].twoFactorStatus stringoptionalenum	The current two factor authentication status. Possible values: ENABLED, PENDING, DISABLED
keys arrayoptional	The API keys for that role are returned when using a high enough value for the query parameter `depth`.
keys.[ ].expiresAt number	The timestamp the key will expire at.
keys.[ ].group string	The name for a group between 3 and 30 characters.
keys.[ ].prefix string	The prefix the key will be identifier at.
keys.[ ].role string	The name for a role between 3 and 30 characters.

Update Role

To update a single role use this endpoint.

PATCH

/api/v1/iam/groups/:groupName/roles/:roleName

Access

This endpoint requires update permission for the resource iam.roles.

URL Parameter

Name	Description
groupName string	The group name for the role.
roleName string	The name for the role.

Request Body

Name	Description
name stringoptional	The new name for the role.
access arrayoptional	An array containing information about what can be accessed. Default: []
access.[ ].resource string	The resource the access is referring to. The access required to call an API can be gathered from the access part of every API definition. The resource literal * will match any resource.
access.[ ].actions arraystring	The actions that the entity can issue on the resource. Most commonly are: create, read, update, delete.
serviceIdentifier optional	Either a list of service identifier that belong to the role this field was used at or the wildcard character `*` that will match any service identifier.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier optional	Either a list of device identifier that belong to the role this field was used at or the wildcard character `*` that will match any device identifier.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Delete single Role

Calling this endpoint will delete the role and all other resources belonging to that role such as users and API keys.

DELETE

/api/v1/iam/groups/:groupName/roles/:roleName

Access

This endpoint requires delete permission for the resource iam.roles.

URL Parameter

Name	Description
groupName string	The group name for the role.
roleName string	The name for the role.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Create User

Call this endpoint to create a user. A code is returned that can be used to let the user finish the sign up process himself.

POST

/api/v1/iam/groups/:groupName/roles/:roleName/users

Access

This endpoint requires create permission for the resource iam.users.

URL Parameter

Name	Description
groupName string	The group name for the role.
roleName string	The name for the role.

Query Parameter

Name	Description
validFor integeroptional	This parameter defines the duration (in milliseconds) an unpaired user account is valid. Defaults to five minutes. In this timeframe the code returned by this endpoint can be given to the user which then can create an account with a preferred password. Default: 300000

Request Body

Name	Description
name string	The name for that user
deviceIdentifier optional	Either a list of device identifier that belong to the user or the wildcard character `*` that will match any device identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
serviceIdentifier optional	Either a list of service identifier that belong to the user or the wildcard character `*` that will match any service identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.

Response

Name	Description
group string	The group for the given user.
role string	The role for the given user.
name string	The user name.
code stringoptional	The code is available within the sign up process. If a user was created and has yet to sign up, the code is available until it expires. See `expiresAt` for more information.
expiresAt integeroptional	The UTC timestamp at which the sign up process can no longer be completed and the user will be deleted automatically.
serviceIdentifier optional	Either a list of service identifier that belong to the user or the wildcard character `*` that will match any service identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier optional	Either a list of device identifier that belong to the user or the wildcard character `*` that will match any device identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
twoFactorStatus stringoptionalenum	The current two factor authentication status. Possible values: ENABLED, PENDING, DISABLED

Sign Up

This endpoint should be used after calling the Create User endpoint. While the other endpoint returns a code, this code can be used here to create a user password combination.

POST

/api/v1/iam/signup

Request Body

Name	Description
code stringoptional	The code is available within the sign up process. If a user was created and has yet to sign up, the code is available until it expires. See `expiresAt` for more information.
name string	The user name.
password string	A password containing at least one lower case, one upper case character, one digit, and at least one of the special characters `!@#$%^&*-_`. The minimum length is eight characters.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

List User

Get a list of all known users.

GET

/api/v1/iam/users

Access

This endpoint requires read permission for the resource iam.users.

Response

Name	Description
group string	The group for the given user.
role string	The role for the given user.
name string	The user name.
code stringoptional	The code is available within the sign up process. If a user was created and has yet to sign up, the code is available until it expires. See `expiresAt` for more information.
expiresAt integeroptional	The UTC timestamp at which the sign up process can no longer be completed and the user will be deleted automatically.
external booleanoptional	Set to true if a user is from an external oauth provider. The reset function is permitted for external user.
serviceIdentifier optional	Either a list of service identifier that belong to the user or the wildcard character `*` that will match any service identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier optional	Either a list of device identifier that belong to the user or the wildcard character `*` that will match any device identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
twoFactorStatus stringoptionalenum	The current two factor authentication status. Possible values: ENABLED, PENDING, DISABLED

Change Password

In order to change your own password, use this endpoint. The old as well as the new passwords need to be provided.

PATCH

/api/v1/iam/users/password

Request Body

Name	Description
newPassword string	A password containing at least one lower case, one upper case character, one digit, and at least one of the special characters `!@#$%^&*-_`. The minimum length is eight characters.
oldPassword string	A password containing at least one lower case, one upper case character, one digit, and at least one of the special characters `!@#$%^&*-_`. The minimum length is eight characters.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Get User

Returns a single user by name.

GET

/api/v1/iam/users/:userName

Access

This endpoint requires read permission for the resource iam.users.

URL Parameter

Name	Description
userName string	The name for the user.

Response

Name	Description
group string	The group for the given user.
role string	The role for the given user.
name string	The user name.
code stringoptional	The code is available within the sign up process. If a user was created and has yet to sign up, the code is available until it expires. See `expiresAt` for more information.
expiresAt integeroptional	The UTC timestamp at which the sign up process can no longer be completed and the user will be deleted automatically.
external booleanoptional	Set to true if a user is from an external oauth provider. The reset function is permitted for external user.
serviceIdentifier optional	Either a list of service identifier that belong to the user or the wildcard character `*` that will match any service identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier optional	Either a list of device identifier that belong to the user or the wildcard character `*` that will match any device identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
twoFactorStatus stringoptionalenum	The current two factor authentication status. Possible values: ENABLED, PENDING, DISABLED

Update a single user

Updates the service or device identifier filter for the given user.

PATCH

/api/v1/iam/users/:userName

Access

This endpoint requires update permission for the resource iam.users.

URL Parameter

Name	Description
userName string	The name for the user.

Request Body

Name	Description
serviceIdentifier optional	Either a list of service identifier that belong to the user this field was used at or the wildcard character `*` that will match any service identifier.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier optional	Either a list of device identifier that belong to the user this field was used at or the wildcard character `*` that will match any device identifier.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
role stringoptional	The role for the given user.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Reset User

Calling this endpoint will reset the user and generate a new code for that user.

POST

/api/v1/iam/users/:userName/reset

Access

This endpoint requires update permission for the resource iam.users.

URL Parameter

Name	Description
userName string	The name for the user.

Query Parameter

Name	Description
validFor integeroptional	This parameter defines the duration (in milliseconds) an unpaired user account is valid. Defaults to five minutes. In this timeframe the code returned by this endpoint can be given to the user which then can create an account with a preferred password. Default: 300000

Response

Name	Description
group string	The group for the given user.
role string	The role for the given user.
name string	The user name.
code stringoptional	The code is available within the sign up process. If a user was created and has yet to sign up, the code is available until it expires. See `expiresAt` for more information.
expiresAt integeroptional	The UTC timestamp at which the sign up process can no longer be completed and the user will be deleted automatically.
serviceIdentifier optional	Either a list of service identifier that belong to the user or the wildcard character `*` that will match any service identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any service. Constant value: *
Alternative 2array	An array of service identifier the entity has access to.
deviceIdentifier optional	Either a list of device identifier that belong to the user or the wildcard character `*` that will match any device identifier. If unset, the access will be handled by the role the user belongs to.
Alternative 1string	The literal value * will grant access to any device. Constant value: *
Alternative 2array	An array of device identifier the entity has access to.
twoFactorStatus stringoptionalenum	The current two factor authentication status. Possible values: ENABLED, PENDING, DISABLED

Delete User

Delete a single user, given its name.

DELETE

/api/v1/iam/users/:userName

Access

This endpoint requires delete permission for the resource iam.users.

URL Parameter

Name	Description
userName string	The name for the user.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Create API Key

Create a new API key within the given group and role.

POST

/api/v1/iam/keys/groups/:groupName/roles/:roleName

Access

This endpoint requires create permission for the resource iam.keys.

URL Parameter

Name	Description
groupName string	The group name for the role.
roleName string	The name for the role.

Request Body

Name	Description
duration stringoptional	The duration the key should be active with a maximum value of three months. Format is a number followed by one of the characters `ywdhms`. Multiple things in descending order can be set and must be seperated with a space. E.g. `2y 3w 20d`. Defaults to 30 days. Default: 30D

Response

Name	Description
expiresAt number	The timestamp the key will expire at.
group string	The name for a group between 3 and 30 characters.
prefix string	The prefix the key will be identifier at.
role string	The name for a role between 3 and 30 characters.
key string	The actual key to be used inside requests as a header. The key is formatted as `prefix.secret`. The secret is only returned once on key creation and can not be accessed any time later. Both, the prefix and the secret, do make up the key.

List all API Keys

List all available API keys.

GET

/api/v1/iam/keys

Access

This endpoint requires read permission for the resource iam.keys.

Response

Name	Description
expiresAt number	The timestamp the key will expire at.
group string	The name for a group between 3 and 30 characters.
prefix string	The prefix the key will be identifier at.
role string	The name for a role between 3 and 30 characters.

Delete all API Keys

Delete all API Keys.

DELETE

/api/v1/iam/keys

Access

This endpoint requires delete permission for the resource iam.keys.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Get API Key

Calling this endpoint will return a single API key identified by the key prefix.

GET

/api/v1/iam/keys/:keyPrefix

Access

This endpoint requires read permission for the resource iam.keys.

URL Parameter

Name	Description
keyPrefix string	The prefix the key will be identifier at.

Response

Name	Description
expiresAt number	The timestamp the key will expire at.
group string	The name for a group between 3 and 30 characters.
prefix string	The prefix the key will be identifier at.
role string	The name for a role between 3 and 30 characters.

Update API Key

The update endpoint does the same as deleting and creating a new API key. However, due to the fact the client can omit the group and role name, it is easier to use.

PATCH

/api/v1/iam/keys/:keyPrefix

Access

This endpoint requires update permission for the resource iam.keys.

URL Parameter

Name	Description
keyPrefix string	The prefix the key will be identifier at.

Request Body

Name	Description
duration stringoptional	The duration the key should be active with a maximum value of three months. Format is a number followed by one of the characters `ywdhms`. Multiple things in descending order can be set and must be seperated with a space. E.g. `2y 3w 20d`. Defaults to 30 days. Default: 30D

Response

Name	Description
expiresAt number	The timestamp the key will expire at.
group string	The name for a group between 3 and 30 characters.
prefix string	The prefix the key will be identifier at.
role string	The name for a role between 3 and 30 characters.
key string	The actual key to be used inside requests as a header. The key is formatted as `prefix.secret`. The secret is only returned once on key creation and can not be accessed any time later. Both, the prefix and the secret, do make up the key.

Delete API Key

Calling this endpoint will delete a single API key identified by the key prefix.

DELETE

/api/v1/iam/keys/:keyPrefix

Access

This endpoint requires delete permission for the resource iam.keys.

URL Parameter

Name	Description
keyPrefix string	The prefix the key will be identifier at.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Add Pairing

Adds a pairing to the highest applicable entity for the user.

INFO

All pairing endpoints are used to allow user to pair devices to their own account, role, or the group they belong to. This endpoint should be used by external client mostly. The device identifier will be added to either the user, the role or the group depending on the access. If the token contains the access iam.pair.user the device will be paired with the user itself. Furthermore, having the access to iam.pair.role or iam.pair.group will store the device within the role or group respectively.

POST

/api/v1/iam/pair

Request Body

Name	Description

Response

Name	Description

List Pairings

Returns a list of all devices the user has access to.

GET

/api/v1/iam/pair

Response

Name	Description
deviceIdentifier arraystring	An array of device identifier that should be paired with the entity or removed from it.

Delete Pairing

Removes a pairing between the device and the client.

DELETE

/api/v1/iam/pair

Request Body

Name	Description
deviceIdentifier arraystring	An array of device identifier that should be paired with the entity or removed from it.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Add Single Pairing

Adds a pairing to the highest applicable entity for the user.

INFO

All pairing endpoints are used to allow user to pair devices to their own account, role, or the group they belong to. This endpoint should be used by external client mostly. The device identifier will be added to either the user, the role or the group depending on the access. If the token contains the access iam.pair.user the device will be paired with the user itself. Furthermore, having the access to iam.pair.role or iam.pair.group will store the device within the role or group respectively.

POST

/api/v1/iam/pair/:deviceIdentifier

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.

Request Body

Name	Description
signature stringoptional	Base64-string that represents the signature that was returned by the SIGN method from the device.
message stringoptional	Message that was signed by the device.

Response

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.
status stringenum	The pair status of the device Possible values: PAIRED, OFFLINE, BAD_SIGN, DEVICE_ERROR

Get Single Pairing

Returns either a 200 if the user is paired with the device or returns a 404 status code if the user has insufficient permission or is not paired with the device.

GET

/api/v1/iam/pair/:deviceIdentifier

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Delete Single Pairing

Removes a pairing between the device and the client.

DELETE

/api/v1/iam/pair/:deviceIdentifier

URL Parameter

Name	Description
deviceIdentifier string	The unique device identifier. Albeit being case insensitive, the upper case representation is used throughout the API.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Get Token Information

This endpoint can be used to get information regarding the token, for example if the token is active or not.

GET

/api/v1/iam/token/info

Response

Name	Description

Get Token

This endpoint can be used to grab a token as well as an optional refresh token.

GET

/api/v1/iam/token

Query Parameter

Name	Description
scope stringoptionalconstant	If the scope offline is specified, an refresh token is also returned and can be used to get a new access token. Constant value: offline
issuer stringoptional	If the issuer is set, the token is generated from an external OAuth provider rather than an internal one. Using an external issuer you can omit the basic authentication header.
sessionToken stringoptional	If an external issuer is present, the session token is required to run the authorization flow without the need of any user input.

Response

Name	Description

Use Refresh Token

To exchange a refresh token use this endpoint.

POST

/api/v1/iam/token

Query Parameter

Name	Description
scope stringconstant	If the scope offline is specified, an refresh token is also returned and can be used to get a new access token. Constant value: offline
grant_type stringconstant	Set in order to indicate that a request token is used to generate new tokens. Constant value: refresh_token

Request Body

Name	Description
refreshToken string	Refresh token that can be used once to generate a new token.

Response

Name	Description
type stringconstant	Value indicating a token response. Constant value: TOKEN
token string	The token that can be used as a header.
refreshToken stringoptional	Refresh token that can be used once to generate a new token.

Well-Known Information

This endpoint can be used to grab the current public key that was used to sign the token. This is useful to verify the origin of the token.

GET

/api/v1/iam/well-known

Response

Name	Description
key string	The public key used to sign the jwt payload.
rotatedKeys arrayoptional	All rotated keys that have been used at least once for the backend. Will be removed from the list after expiration.
rotatedKeys.[ ].key string	The public key that was used in the past to sign the jwt payload.
rotatedKeys.[ ].expiresAt number	The expiration time in UTC timestamp format when a key will not be used anymore.

Authorization Code Callback

This endpoint is used internally to handle authorization code callbacks within the OAuth flow.

GET

/api/v1/iam/callback

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Enable two factor authentication

Call this endpoint to start the two factor authentication process.

POST

/api/v1/iam/2fa/enable

Request Body

Name	Description
password string	A password containing at least one lower case, one upper case character, one digit, and at least one of the special characters `!@#$%^&*-_`. The minimum length is eight characters.

Response

Name	Description
secret string	The secret generated for the specific user.
uri string	The otpauth uri generated for the specific user.
token string	The token that needs to be used in the verify request.

Verify two factor authentication

This endpoint should be called once after enabling two factor authentication. It ensures that the setup was successful.

POST

/api/v1/iam/2fa/verify

Request Body

Name	Description
token string	The token from the initial token request using two factor authentication.
code stringoptional	The code generated by the second mean of authentication.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Disable two factor authentication

This endpoint can be used to disable two factor authentication again.

POST

/api/v1/iam/2fa/disable

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

Request token with 2FA

Returns the actual token after login in with 2FA enabled.

POST

/api/v1/iam/2fa/token

Request Body

Name	Description
token string	The token from the initial token request using two factor authentication.
code stringoptional	The code generated by the second mean of authentication.

Response

Name	Description
type stringconstant	Value indicating a token response. Constant value: TOKEN
token string	The token that can be used as a header.
refreshToken stringoptional	Refresh token that can be used once to generate a new token.

Add Pairing (Deprecated)

Adds a pairing to the highest applicable entity for the user.

INFO

All pairing endpoints are used to allow user to pair devices to their own account, role, or the group they belong to. This endpoint should be used by external client mostly. The device identifier will be added to either the user, the role or the group depending on the access. If the token contains the access iam.pair.user the device will be paired with the user itself. Furthermore, having the access to iam.pair.role or iam.pair.group will store the device within the role or group respectively.

WARNING

This endpoint is deprecated and will be removed in version five at the latest

POST

/api/v1/pair

Request Body

Name	Description
systemIdentifier arraystring	An array of device identifier that should be paired with the entity. The deprecated pairing endpoint uses the word system identifier as a synonym for the word device identifier.

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.

List Pairings (Deprecated)

Returns a list of all devices the user has access to.

WARNING

This endpoint is deprecated and will be removed in version five at the latest

GET

/api/v1/pair

Response

Name	Description
systemIdentifier arraystring	An array of device identifier that should be paired with the entity. The deprecated pairing endpoint uses the word system identifier as a synonym for the word device identifier.

Delete Pairing (Deprecated)

Removes a pairing between the device and the client.

WARNING

This endpoint is deprecated and will be removed in version five at the latest

DELETE

/api/v1/pair

Response

This endpoint simply returns Status 204 to indicate a successful operation and to save bandwidth.