Auth REST API Scopes and Permissions

Access tokens contain a set of claims in the form of name-value pairs. One such pair is the scope (aka permissions) claim, which constains one or more permissions. These scopes tell the resource server which services the token grants access to.

To see how to create new permissions, visit Permissions How-Tos

For example, the decoded JWT access token, below, has the claim "scope": "auth.clients.list". This specific scope allows the client application to list all the clients.

Decoded JWT Access Token

{
  "sub": "1234567890",
  "jti": "uniquejwtid",
  "gty": "authorization_code",
  "azp": 9019,
  "aud": [
    "https://my.domain.org/_api/auth/mytenant"
  ],
  "scope": "auth.clients.list",
  "iat": 1622138948,
  "exp": 1622142548,
  "iss": "https://my.domain.org/_api/auth/mytenant"
}

For reference, the encoded JWT access token is shown below. You can decode this token in https://jwt.io and get the same result as above.

Encoded JWT Access Tokens

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwianRpIjoidW5pcXVland0aWQiLCJndHkiOiJhdXRob3JpemF0aW9uX2NvZGUiLCJhenAiOjkwMTksImF1ZCI6WyJodHRwczovL215LmRvbWFpbi5vcmcvX2FwaS9hdXRoL215dGVuYW50Il0sInNjb3BlIjoiYXV0aC5jbGllbnRzLmxpc3QiLCJpYXQiOjE2MjIxMzg5NDgsImV4cCI6MTYyMjE0MjU0OCwiaXNzIjoiaHR0cHM6Ly9teS5kb21haW4ub3JnL19hcGkvYXV0aC9teXRlbmFudCJ9.y209KU6qNkmOiYijnTHlYIZHHxiSbpQt3uB_K5TiXh0

API Audience and Scope Configuration

In order for the token-protected API endpoint to be accessible to the client application, the client application must be linked to the specific resource server. This is known as the “resource” or “audience”.

For more information on APIs, go to API to learn about resource servers.

To see how to link a client application to a resource server, go to Add Client To API How-Tos.

And finally, the User behind the client application must also have the necessary permissions, or scopes, to access the API endpoint. See below for details.

Assign Permissions to a User

To assign permissions to a user, you must configure a role with the necessary permissions.

Create a role linked to a client application.
Assign permissions to the role.
Assign the role to a user group.
Assign the user to the same user group as last step.

Permission Fields

Field	Description	Example
Application	The name of the client application for which this permission was created	My Sample Application
Name	The scope of the permission	auth.clients.list
Description	The description of what the permission allows	Permits listing the auth clients

List of Auth REST API Scopes

Below is a list of the scopes supported by the Auth REST API.

/**
 * @module The Authorization Scopes supported by the Auth REST API
 */

export const SCOPE = {
  AUDIT_LOGS: {
    LIST: 'auth.auditLogs.list'
  },
  USER_TRUSTED_DEVICES: {
    LIST: 'auth.userTrustedDevices.list',
    CREATE: 'auth.userTrustedDevices.create',
    DELETE: 'auth.userTrustedDevices.delete',
    UPDATE: 'auth.userTrustedDevices.update'
  },
  USERS: {
    LIST: 'auth.users.list',
    CREATE: 'auth.users.create',
    DELETE: 'auth.users.delete',
    UPDATE: 'auth.users.update',
    SET_PASSWORD: 'auth.users.set_password'
  },
  TENANTS: {
    LIST: 'auth.tenants.list',
    CREATE: 'auth.tenants.create',
    DELETE: 'auth.tenants.delete',
    UPDATE: 'auth.tenants.update'
  },
  GROUPS: {
    LIST: 'auth.groups.list',
    CREATE: 'auth.groups.create',
    DELETE: 'auth.groups.delete',
    UPDATE: 'auth.groups.update'
  },
  PERMISSIONS: {
    LIST: 'auth.permissions.list',
    CREATE: 'auth.permissions.create',
    DELETE: 'auth.permissions.delete',
    UPDATE: 'auth.permissions.update'
  },
  NAMESPACES: {
    LIST: 'auth.namespaces.list',
    CREATE: 'auth.namespaces.create',
    DELETE: 'auth.namespaces.delete',
    UPDATE: 'auth.namespaces.update'
  },
  ROLES: {
    LIST: 'auth.roles.list',
    CREATE: 'auth.roles.create',
    DELETE: 'auth.roles.delete',
    UPDATE: 'auth.roles.update'
  },
  CLIENTS: {
    LIST: 'auth.clients.list',
    CREATE: 'auth.clients.create',
    DELETE: 'auth.clients.delete',
    UPDATE: 'auth.clients.update',
    JWK_CREATE: 'auth.clients.jwk_create',
    JWK_UPDATE: 'auth.clients.jwk_update'
  },
  IDENTITY_PROVIDERS: {
    LIST: 'auth.identityProviders.list',
    CREATE: 'auth.identityProviders.create',
    DELETE: 'auth.identityProviders.delete',
    UPDATE: 'auth.identityProviders.update'
  },
  RESOURCE_SERVERS: {
    LIST: 'auth.resourceServers.list',
    CREATE: 'auth.resourceServers.create',
    DELETE: 'auth.resourceServers.delete',
    UPDATE: 'auth.resourceServers.update'
  },
  EMAIL: {
    SEND: 'auth.send.email'
  },
  OIDC_SESSIONS: {
    LIST: 'auth.oidc.sessions.list',
    DELETE: 'auth.oidc.sessions.delete'
  },
  OIDC_GRANTS: {
    LIST: 'auth.oidc.grants.list',
    DELETE: 'auth.oidc.grants.delete'
  },
  CERTIFICATES: {
    UPLOAD_OR_CREATE: 'auth.certificates.create'
  },
  TOKENS: {
    LIST: 'auth.tokens.list'
  },
  CREDENTIALS: {
    CREATE: 'auth.credentials.create',
    UPDATE: 'auth.credentials.update',
    DELETE: 'auth.credentials.delete',
    LIST: 'auth.credentials.list',
    SET_LEVEL: 'auth.credentials.setLevel'
  }
};