Applications

Download OpenAPI specification:Download

Manage your applications and their clients. An application requires at least one client, the first client is created automatically and set as default. The application can be configured to use additional clients which can be added later. Application APIs are authorized using an access token of a relevant app or using an admin access token of the management application.

Create client

Create a new client.

Required permissions: apps:create, apps:edit.

SecurityOAuth2: ClientAccessToken or OAuth2: AdminAccessToken
Request
path Parameters
appId
required
string
Request Body schema: application/json
required
Any of:
name
required
string

Name of the client

description
string

Short description of the client

resources
Array of strings

List of resources IDs associated with this client

authentication_protocol
string
Default: "oidc"

Authentication protocol used by the client

Enum: "oidc" "saml"
client_group_id
string

Id of client group to associate with

default_custom_claims
Array of strings

List of client default custom claims

Items Enum: "tid" "fname" "lname" "mname" "email" "email_verified" "phone_number" "phone_number_verified" "groups" "new_user" "birthday" "language" "city" "address" "country" "street_address" "address_type" "webauthn" "roles" "ts_roles" "role_values" "ts_permissions" "permissions" "approval_data" "custom_group_data" "username" "secondary_phone_numbers" "secondary_emails" "picture" "created_at" "last_auth" "auth_time" "external_account_id" "external_user_id" "app_name" "custom_data" "custom_app_data"
short_cookies_samesite_type
string
Default: "lax"

Short cookies samesite type. Possible values: "none", "lax", "strict". Default: "lax"

Enum: "lax" "none"
redirect_uris
required
Array of strings

List of URIs approved for redirects for your client

client_type
string
Default: "web"

Client type

Enum: "web" "native"
response_types
Array of strings
Default: ["code","id_token"]
Items Enum: "code" "id_token"
token_endpoint_auth_method
string
Deprecated
Default: "client_secret_basic"

This field is deprecated- to configure pkce use "pkce" field instead

Enum: "client_secret_basic" "self_signed_tls_client_auth" "tls_client_auth" "none" "private_key_jwt"
object

Configuration for an OAuth Device Authorization Flow

object

CIBA authorization flow configuration

is_third_party
boolean

Is third party client

allowed_scopes
Array of strings

Allowed scopes

consent_uri
string

Consent URI

consent_validity_period
number

Consent validity period

pkce
string

PKCE configuration

Enum: "enforcePkceInsteadOfClientCredentials" "enforcePkceAlongsideClientCredentials" "allowPkceAlongsideClientCredentials"
supported_prompts
Array of strings

Supported prompts for the OIDC authentication flow

Items Enum: "login" "consent" "none"
object

Token expiration settings

object

Client authentication configuration

session_expiration
number

Session expiration time (seconds)

enforce_par
boolean

enforce PAR (Pushed Authorization Request) for this client

role_ids
Array of strings

Role IDs

fapi_version_compliancy
boolean

FAPI 2.0 compliancy configuration

Responses
201
400
409
post/v1/applications/{appId}/clients
Request samples
application/json
{
  • "name": "My Client",
  • "description": "string",
  • "resources": [
    ],
  • "authentication_protocol": "oidc",
  • "client_group_id": "string",
  • "default_custom_claims": [
    ],
  • "short_cookies_samesite_type": "lax",
  • "redirect_uris": [],
  • "client_type": "web",
  • "response_types": [
    ],
  • "token_endpoint_auth_method": "client_secret_basic",
  • "device_authorization": {},
  • "ciba_authorization": {},
  • "is_third_party": true,
  • "allowed_scopes": [
    ],
  • "consent_uri": "string",
  • "consent_validity_period": 0,
  • "pkce": "enforcePkceInsteadOfClientCredentials",
  • "supported_prompts": [
    ],
  • "token_expiration": {
    },
  • "authentication_configuration": {
    },
  • "session_expiration": 0,
  • "enforce_par": true,
  • "role_ids": [
    ],
  • "fapi_version_compliancy": true
}
Response samples
application/json
{
  • "app_id": "string",
  • "tenant_id": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "resources": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "authentication_protocol": "oidc",
  • "client_group_id": "string",
  • "default_custom_claims": [
    ],
  • "short_cookies_samesite_type": "lax",
  • "redirect_uris": [
    ],
  • "client_type": "web",
  • "response_types": [
    ],
  • "token_endpoint_auth_method": "client_secret_basic",
  • "pkce": "enforcePkceInsteadOfClientCredentials",
  • "device_authorization": {},
  • "ciba_authorization": {},
  • "supported_prompts": [
    ],
  • "authentication_configuration": {
    },
  • "token_expiration": {
    },
  • "session_expiration": 0,
  • "enforce_par": true,
  • "fapi_version_compliancy": true
}

Get all clients

Retrieves a list of clients for an application.

Required permissions: apps:read.

SecurityOAuth2: ClientAccessToken or OAuth2: AdminAccessToken
Request
path Parameters
appId
required
string
Responses
200
400
get/v1/applications/{appId}/clients
Request samples 
Response samples 
application/json
[
  • {
    }
]
Delete all clients
Deletes all clients for an application.


SecurityOAuth2: ClientAccessToken or OAuth2: AdminAccessToken 
Request 
path Parameters
appId
required
string
 
Responses 
204
400
404
delete/v1/applications/{appId}/clients
Request samples 
Response samples 
application/json
{
  • "message": "Bad request",
  • "error_code": 400
}
Get client by ID
Retrieves a client by client ID. 

Required permissions: apps:read.


SecurityOAuth2: ClientAccessToken or OAuth2: AdminAccessToken 
Request 
path Parameters
clientId
required
string
ID of the client to retrieve


 
appId
required
string
 
Responses 
200
400
404
get/v1/applications/{appId}/clients/{clientId}
Request samples 
Response samples 
application/json
{
  • "app_id": "string",
  • "tenant_id": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "resources": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "authentication_protocol": "oidc",
  • "client_group_id": "string",
  • "default_custom_claims": [
    ],
  • "short_cookies_samesite_type": "lax",
  • "redirect_uris": [
    ],
  • "client_type": "web",
  • "response_types": [
    ],
  • "token_endpoint_auth_method": "client_secret_basic",
  • "pkce": "enforcePkceInsteadOfClientCredentials",
  • "device_authorization": {},
  • "ciba_authorization": {},
  • "supported_prompts": [
    ],
  • "authentication_configuration": {
    },
  • "token_expiration": {
    },
  • "session_expiration": 0,
  • "enforce_par": true,
  • "fapi_version_compliancy": true
}
Update client
Update a client. Note: Fields that are objects cannot be partially updated, since the new value you set will just replace the current one. 

Required permissions: apps:edit, apps:create.


SecurityOAuth2: ClientAccessToken or OAuth2: AdminAccessToken 
Request 
path Parameters
clientId
required
string
ID of the client to update


 
appId
required
string
 
Request Body schema: application/json
required
Any of:
name
string
Name of the client


 
description
string
Short description of the client


 
resources
Array of strings
List of resources IDs associated with this client


 
client_group_id
string
Id of client group to associate with


 
default_custom_claims
Array of strings
List of client default custom claims


Items Enum: "tid" "fname" "lname" "mname" "email" "email_verified" "phone_number" "phone_number_verified" "groups" "new_user" "birthday" "language" "city" "address" "country" "street_address" "address_type" "webauthn" "roles" "ts_roles" "role_values" "ts_permissions" "permissions" "approval_data" "custom_group_data" "username" "secondary_phone_numbers" "secondary_emails" "picture" "created_at" "last_auth" "auth_time" "external_account_id" "external_user_id" "app_name" "custom_data" "custom_app_data"  
short_cookies_samesite_type
string
 Default:  "lax"
Short cookies samesite type. Possible values: "none", "lax", "strict". Default: "lax"


 Enum: "lax" "none"  
redirect_uris
Array of strings
List of URIs approved for redirects for your client


 
client_type
string
 Default:  "web"
Client type


 Enum: "web" "native"  
response_types
Array of strings
 Default:  ["code","id_token"]
Items Enum: "code" "id_token"  
token_endpoint_auth_method
string
 Deprecated 
 Default:  "client_secret_basic"
This field is deprecated- to configure pkce use "pkce" field instead


 Enum: "client_secret_basic" "self_signed_tls_client_auth" "tls_client_auth" "none" "private_key_jwt"  
object
Configuration for an OAuth Device Authorization Flow


 
object
CIBA authorization flow configuration


 
is_third_party
boolean
Is third party client


 
allowed_scopes
Array of strings
Allowed scopes


 
consent_uri
string
Consent URI


 
consent_validity_period
number
Consent validity period


 
pkce
string
PKCE configuration


 Enum: "enforcePkceInsteadOfClientCredentials" "enforcePkceAlongsideClientCredentials" "allowPkceAlongsideClientCredentials"  
supported_prompts
Array of strings
Supported prompts for the OIDC authentication flow


Items Enum: "login" "consent" "none"  
object
Token expiration settings


 
object
Client authentication configuration


 
session_expiration
number
Session expiration time (seconds)


 
enforce_par
boolean
enforce PAR (Pushed Authorization Request) for this client


 
role_ids
Array of strings
Role IDs


 
fapi_version_compliancy
boolean
FAPI 2.0 compliancy configuration


 
Responses 
200
400
404
put/v1/applications/{appId}/clients/{clientId}
Request samples 
application/json
{
  • "name": "My Client",
  • "description": "string",
  • "resources": [
    ],
  • "client_group_id": "string",
  • "default_custom_claims": [
    ],
  • "short_cookies_samesite_type": "lax",
  • "redirect_uris": [],
  • "client_type": "web",
  • "response_types": [
    ],
  • "token_endpoint_auth_method": "client_secret_basic",
  • "device_authorization": {},
  • "ciba_authorization": {},
  • "is_third_party": true,
  • "allowed_scopes": [
    ],
  • "consent_uri": "string",
  • "consent_validity_period": 0,
  • "pkce": "enforcePkceInsteadOfClientCredentials",
  • "supported_prompts": [
    ],
  • "token_expiration": {
    },
  • "authentication_configuration": {
    },
  • "session_expiration": 0,
  • "enforce_par": true,
  • "role_ids": [
    ],
  • "fapi_version_compliancy": true
}
Response samples 
application/json
{
  • "app_id": "string",
  • "tenant_id": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "resources": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "authentication_protocol": "oidc",
  • "client_group_id": "string",
  • "default_custom_claims": [
    ],
  • "short_cookies_samesite_type": "lax",
  • "redirect_uris": [
    ],
  • "client_type": "web",
  • "response_types": [
    ],
  • "token_endpoint_auth_method": "client_secret_basic",
  • "pkce": "enforcePkceInsteadOfClientCredentials",
  • "device_authorization": {},
  • "ciba_authorization": {},
  • "supported_prompts": [
    ],
  • "authentication_configuration": {
    },
  • "token_expiration": {
    },
  • "session_expiration": 0,
  • "enforce_par": true,
  • "fapi_version_compliancy": true
}
Delete client
Delete a client. 

Required permissions: apps:delete, apps:create, apps:edit.


SecurityOAuth2: ClientAccessToken or OAuth2: AdminAccessToken 
Request 
path Parameters
clientId
required
string
ID of the client to delete


 
appId
required
string
 
Responses 
204
400
404
delete/v1/applications/{appId}/clients/{clientId}
Request samples 
Response samples 
application/json
{
  • "message": "Bad request",
  • "error_code": 400
}
Update client resources
Update the list of resources that a client is allowed to explicitly request access to


SecurityOAuth2: ClientAccessToken or OAuth2: AdminAccessToken 
Request 
path Parameters
clientId
required
string
 
appId
required
string
 
Request Body schema: application/json
required
resource_ids
required
Array of strings
List of resources this application is allowed to explicitly request access to


 
Responses 
200
put/v1/applications/{appId}/clients/{clientId}/resources
Request samples 
application/json
{
  • "resource_ids": [
    ]
}
Response samples 
application/json
{
  • "app_id": "string",
  • "tenant_id": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "name": "string",
  • "description": "string",
  • "resources": [
    ],
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "authentication_protocol": "oidc",
  • "client_group_id": "string",
  • "default_custom_claims": [
    ],
  • "short_cookies_samesite_type": "lax",
  • "redirect_uris": [
    ],
  • "client_type": "web",
  • "response_types": [
    ],
  • "token_endpoint_auth_method": "client_secret_basic",
  • "pkce": "enforcePkceInsteadOfClientCredentials",
  • "device_authorization": {},
  • "ciba_authorization": {},
  • "supported_prompts": [
    ],
  • "authentication_configuration": {
    },
  • "token_expiration": {
    },
  • "session_expiration": 0,
  • "enforce_par": true,
  • "fapi_version_compliancy": true
}
Create app
Create a new application with a default client. The fields marked as deprecated are now managed on the client level. To update a default client, create additional clients, or fetch all app clients, use /clients or applications/{appId}/clients endpoints. 

Required permissions: apps:create, [appId]:create.


SecurityOAuth2: ClientAccessToken 
Request 
Request Body schema: application/json
required
app_name
required
string
Name of the application


 
app_description
string
Short description of the application


 
service_providers
Array of strings
List of service provider IDs associated with this application


 
object
Configures the application as the Authentication Hub of this tenant, allowing other apps to use it to perform a centralized login


 
login_uri
string
URI used to redirect the user to the login page of the application (when needed)


 
invite_member_uri
string
URI used to redirect the member to the login page of the application (when needed)


 
invite_client_id
string
Client used for the email magic link invitation flow


 
invite_member_email_expiration_minutes
number
 Default:  2880
Member invite email link expiration in minutes


 
signing_key_enabled
boolean
 Default:  false
Determines if application specific signing key is enabled


 
client_type
string
 Deprecated 
 Default:  "web"
Client type of the default client


 Enum: "web" "native"  
client_display_name
required
string
 Deprecated 
Client name of the default client to display when needed


 
client_description
string
 Deprecated 
Short description of the default client


 
first_client_authentication_protocol
string
Defines the first client authentication protocol.


 Enum: "oidc" "saml"  
ApiCreateOidcClientInput (object) or ApiCreateSamlClientInput (object)
Creates first client for the application. Client can be OIDC or SAML, depending what is set in first_client_authentication_protocol


 
redirect_uris
Array of strings
 Deprecated 
List of URI approved for redirects for your default client


 
logo
string
URI of your application's logo, such as for email templates


 
resources
Array of strings
 Deprecated 
List of resources IDs associated with the default client


 
allow_public_signup
boolean
 Default:  false
Determines if the application is allowed to request to create new users via login flows


 
object
 Deprecated 
Configuration for an OAuth Device Authorization Flow of the default client


 
object
 Deprecated 
CIBA authorization flow configuration of the default client


 
client_auth_method
string
 Deprecated 
 Default:  "client_secret_basic"
This field is deprecated- to configure pkce use "pkce" field instead


 Enum: "client_secret_basic" "self_signed_tls_client_auth" "tls_client_auth" "none" "private_key_jwt"  
subdomain
string
Subdomain of Org admin portal that can be offered for organizations to manage their users (when needed)


 
custom_domain
string
Domain of the application that can be offered for the application to be accessed from


 
pkce
string
PKCE configuration for client


 Enum: "enforcePkceInsteadOfClientCredentials" "enforcePkceAlongsideClientCredentials" "allowPkceAlongsideClientCredentials"  
should_delete_signing_key
boolean
 Default:  false
Determines whether the application-specific signing key should be deleted when disabled. If deleted, any tokens previously issued with this key will no longer be valid.


 
Responses 
201
400
409
post/v1/applications
Request samples 
application/json
{
  • "app_name": "My App",
  • "app_description": "string",
  • "service_providers": [
    ],
  • "authenticator_preferences": {},
  • "login_uri": "https://www.example.com/login",
  • "invite_member_uri": "https://www.example.com/login",
  • "invite_client_id": "string",
  • "invite_member_email_expiration_minutes": 2880,
  • "signing_key_enabled": false,
  • "client_type": "web",
  • "client_display_name": "string",
  • "client_description": "string",
  • "first_client_authentication_protocol": "oidc",
  • "first_client": {
    },
  • "redirect_uris": [],
  • "logo": "string",
  • "resources": [
    ],
  • "allow_public_signup": false,
  • "device_authorization": {},
  • "ciba_authorization": {},
  • "client_auth_method": "client_secret_basic",
  • "subdomain": "myapp",
  • "custom_domain": "myapp.com",
  • "pkce": "enforcePkceInsteadOfClientCredentials",
  • "should_delete_signing_key": false
}
Response samples 
application/json
{
  • "result": {
    }
}
Get all apps
Retrieves a list of all applications with their default clients. The fields marked as deprecated are now managed on the client level. To update a default client, create additional clients, or fetch all app clients, use /clients or applications/{appId}/clients endpoints. 

Required permissions: apps:read, apps:list, [appId]:read, [appId]:list.


SecurityOAuth2: ClientAccessToken 
Responses 
200
400
get/v1/applications
Request samples 
Response samples 
application/json
{
  • "result": [
    ]
}
Get all apps basic information
Retrieves a list of all applications with their basic information. 

Required permissions: apps:list, users:read, organizations:read, roles:read, orgs:read, [appId]:list.


SecurityOAuth2: ClientAccessToken 
Responses 
200
400
get/v1/applications/list
Request samples 
Response samples 
application/json
{
  • "result": []
}
Get app by ID
Retrieves an application by application ID with the default client. The fields marked as deprecated are now managed on the client level. To update a default client, create additional clients, or fetch all app clients, use /clients or applications/{appId}/clients endpoints. 

Required permissions: apps:read, [appId]:read.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
appId
required
string
ID of the application to retrieve


 
Responses 
200
400
404
get/v1/applications/{appId}
Request samples 
Response samples 
application/json
{
  • "result": {
    }
}
Update app
Updates an application. The fields marked as deprecated are now managed on the client level. To update a default client, create additional clients, or fetch all app clients, use /clients or applications/{appId}/clients endpoints. Note: Fields that are objects cannot be partially updated, since the new value you set will just replace the current one. 

Required permissions: apps:edit, [appId]:edit.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
appId
required
string
ID of the application to update


 
Request Body schema: application/json
required
app_name
string
Name of the application


 
app_description
string
Short description of the application


 
service_providers
Array of strings
List of service provider IDs associated with this application


 
object
Configures the application as the Authentication Hub of this tenant, allowing other apps to use it to perform a centralized login


 
login_uri
string
URI used to redirect the user to the login page of the application (when needed)


 
invite_member_uri
string
URI used to redirect the member to the login page of the application (when needed)


 
invite_client_id
string
Client used for the email magic link invitation flow


 
invite_member_email_expiration_minutes
number
 Default:  2880
Member invite email link expiration in minutes


 
signing_key_enabled
boolean
 Default:  false
Determines if application specific signing key is enabled


 
client_type
string
 Deprecated 
 Default:  "web"
Client type of the default client


 Enum: "web" "native"  
client_display_name
string
 Deprecated 
Client name of the default client to display when needed


 
client_description
string
 Deprecated 
Short description of the default client


 
first_client_authentication_protocol
string
Defines the first client authentication protocol.


 Enum: "oidc" "saml"  
ApiCreateOidcClientInput (object) or ApiCreateSamlClientInput (object)
Creates first client for the application. Client can be OIDC or SAML, depending what is set in first_client_authentication_protocol


 
redirect_uris
Array of strings
 Deprecated 
List of URI approved for redirects for your default client


 
logo
string
URI of your application's logo, such as for email templates


 
resources
Array of strings
 Deprecated 
List of resources IDs associated with the default client


 
allow_public_signup
boolean
 Default:  false
Determines if the application is allowed to request to create new users via login flows


 
object
 Deprecated 
Configuration for an OAuth Device Authorization Flow of the default client


 
object
 Deprecated 
CIBA authorization flow configuration of the default client


 
client_auth_method
string
 Deprecated 
 Default:  "client_secret_basic"
This field is deprecated- to configure pkce use "pkce" field instead


 Enum: "client_secret_basic" "self_signed_tls_client_auth" "tls_client_auth" "none" "private_key_jwt"  
subdomain
string
Subdomain of Org admin portal that can be offered for organizations to manage their users (when needed)


 
custom_domain
string
Domain of the application that can be offered for the application to be accessed from


 
pkce
string
PKCE configuration for client


 Enum: "enforcePkceInsteadOfClientCredentials" "enforcePkceAlongsideClientCredentials" "allowPkceAlongsideClientCredentials"  
should_delete_signing_key
boolean
 Default:  false
Determines whether the application-specific signing key should be deleted when disabled. If deleted, any tokens previously issued with this key will no longer be valid.


 
Responses 
200
400
404
put/v1/applications/{appId}
Request samples 
application/json
{
  • "app_name": "My App",
  • "app_description": "string",
  • "service_providers": [
    ],
  • "authenticator_preferences": {},
  • "login_uri": "https://www.example.com/login",
  • "invite_member_uri": "https://www.example.com/login",
  • "invite_client_id": "string",
  • "invite_member_email_expiration_minutes": 2880,
  • "signing_key_enabled": false,
  • "client_type": "web",
  • "client_display_name": "string",
  • "client_description": "string",
  • "first_client_authentication_protocol": "oidc",
  • "first_client": {
    },
  • "redirect_uris": [],
  • "logo": "string",
  • "resources": [
    ],
  • "allow_public_signup": false,
  • "device_authorization": {},
  • "ciba_authorization": {},
  • "client_auth_method": "client_secret_basic",
  • "subdomain": "myapp",
  • "custom_domain": "myapp.com",
  • "pkce": "enforcePkceInsteadOfClientCredentials",
  • "should_delete_signing_key": false
}
Response samples 
application/json
{
  • "result": {
    }
}
Delete app
Delete an application. 

Required permissions: apps:delete, [appId]:delete.


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
appId
required
string
ID of the application to delete


 
Responses 
204
400
404
delete/v1/applications/{appId}
Request samples 
Response samples 
application/json
{
  • "message": "Bad request",
  • "error_code": 400
}
Update app resourcesDeprecated
Update the list of resources that a default client of the application is allowed to explicitly request access to


SecurityOAuth2: ClientAccessToken 
Request 
path Parameters
appId
required
string
 
Request Body schema: application/json
required
resource_ids
required
Array of strings
List of resources this application is allowed to explicitly request access to


 
Responses 
200
put/v1/applications/{appId}/resources
Request samples 
application/json
{
  • "resource_ids": [
    ]
}
Response samples 
application/json
{
  • "result": {
    }
}