API docs by Redocly

Bonterra API Endpoints (${bonterra_api_version})

Download OpenAPI specification:

A Bonterra API Gateway that routes requests to internal Bonterra APIs

Oauth2

Oauth2 related operations

Generate OAuth token

This endpoint is used to generate an OAuth token by redirecting the request to Bonterra Auth's token endpoint.

header Parameters
Content-Type
required
string
Default: application/json

Content type header

Request Body schema: application/json
required

Token request

grant_type
required
string

The grant type of the token request. Accepted values are 'client_credentials', 'authorization_code' and 'refresh_token'.

client_id
string

The client id provided by the Bonterra API application.

client_secret
string

The client secret provided by the Bonterra API application.

audience
string

Required parameter that identifies the API you want to access. Use the API origin (https://api.bonterra.network) as the audience value.

scope
string

The scope of the token request.

redirect_uri
string

The redirect uri provided by the Bonterra API application, this is used for standalone management API.

refresh_token
string

The refresh token provided by the Bonterra API application.

code
string

The authorization code returned by the /authorize call.

code_verifier
string

The code verifier provided by the Bonterra API application (for PKCE).

Responses

Response Schema: application/json
access_token
required
string

The access token issued by the authorization server.

expires_in
required
string

The lifetime in seconds of the access token.

token_type
required
string

The type of the token issued.

refresh_token
string

The refresh token issued by the authorization server.

id_token
string

The id token issued by the authorization server.

Request samples

Content type
application/json
{
  • "grant_type": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "audience": "string",
  • "scope": "string",
  • "redirect_uri": "string",
  • "refresh_token": "string",
  • "code": "string",
  • "code_verifier": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": "string",
  • "token_type": "string",
  • "refresh_token": "string",
  • "id_token": "string"
}

Management

Management related operations

Users

User management operations

Create a new user in the Bonterra Auth Service

Create a new user in the Bonterra Auth Service

Authorizations:
authorizer-lambdaapi_key
header Parameters
Content-Type
required
string
Default: application/json

Content type header

Request Body schema: application/json
required

User creation request

bonterraAuthId
string

The unique identifier for the user in the Bonterra Auth.

email
required
string <email>

The user's email address

object

User metadata for the user

blocked
boolean

Whether the user is blocked

emailVerified
boolean

Whether the email has been verified. Passing in true will NOT send a user verification email.

phoneNumber
string

The user's phone number

phoneVerified
boolean

Whether the phone number has been verified

username
string

The user's username

familyName
string

The user's family name

givenName
string

The user's given name

name
string

The user's full name

nickname
string

The user's nickname

picture
string

The URL of the user's profile picture

isBonterraGrants
boolean
Default: false

Whether the user is a Bonterra grants user

verifyEmail
boolean
Default: false

Whether to send a verification email

verifyPhoneNumber
boolean
Default: false

Whether to send a verification SMS

password
required
string >= 8 characters

The user's password

Responses

Response Schema: application/json
bonterraAuthId
string

The unique identifier for the user in the Bonterra Auth.

email
required
string <email>

The user's email address

object

User metadata for the user

blocked
boolean

Whether the user is blocked

emailVerified
required
boolean

Whether the email has been verified. Passing in true will NOT send a user verification email.

phoneNumber
string

The user's phone number

phoneVerified
boolean

Whether the phone number has been verified

username
string

The user's username

familyName
string

The user's family name

givenName
string

The user's given name

name
string

The user's full name

nickname
string

The user's nickname

picture
string

The URL of the user's profile picture

isBonterraGrants
boolean
Default: false

Whether the user is a Bonterra grants user

userId
required
string

The unique identifier for the user

createdAt
required
string <date-time>

The date and time when the user was created

updatedAt
required
string <date-time>

The date and time when the user was last updated

required
Array of objects

The user's identities

multifactor
Array of strings

The user's multifactor authentication methods

lastIp
string

The last IP address used by the user

lastLogin
string <date-time>

The date and time of the user's last login

loginsCount
integer

The number of times the user has logged in

Request samples

Content type
application/json
{
  • "bonterraAuthId": "string",
  • "email": "user@example.com",
  • "userMetadata": { },
  • "blocked": true,
  • "emailVerified": true,
  • "phoneNumber": "string",
  • "phoneVerified": true,
  • "username": "string",
  • "familyName": "string",
  • "givenName": "string",
  • "name": "string",
  • "nickname": "string",
  • "picture": "string",
  • "isBonterraGrants": false,
  • "verifyEmail": false,
  • "verifyPhoneNumber": false,
  • "password": "stringst"
}

Response samples

Content type
application/json
{
  • "bonterraAuthId": "string",
  • "email": "user@example.com",
  • "userMetadata": { },
  • "blocked": true,
  • "emailVerified": true,
  • "phoneNumber": "string",
  • "phoneVerified": true,
  • "username": "string",
  • "familyName": "string",
  • "givenName": "string",
  • "name": "string",
  • "nickname": "string",
  • "picture": "string",
  • "isBonterraGrants": false,
  • "userId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "identities": [
    ],
  • "multifactor": [
    ],
  • "lastIp": "string",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "loginsCount": 0
}

Get a user by bonterra auth id.

Get a user by user id.

Authorizations:
authorizer-lambdaapi_key
path Parameters
user_id
required
string

The ID of the user

query Parameters
fields
string

Fields to include or exclude

has_fields
boolean
Default: true

Whether to include fields

Responses

Response Schema: application/json
bonterraAuthId
string

The unique identifier for the user in the Bonterra Auth.

email
required
string <email>

The user's email address

object

User metadata for the user

blocked
boolean

Whether the user is blocked

emailVerified
required
boolean

Whether the email has been verified. Passing in true will NOT send a user verification email.

phoneNumber
string

The user's phone number

phoneVerified
boolean

Whether the phone number has been verified

username
string

The user's username

familyName
string

The user's family name

givenName
string

The user's given name

name
string

The user's full name

nickname
string

The user's nickname

picture
string

The URL of the user's profile picture

isBonterraGrants
boolean
Default: false

Whether the user is a Bonterra grants user

userId
required
string

The unique identifier for the user

createdAt
required
string <date-time>

The date and time when the user was created

updatedAt
required
string <date-time>

The date and time when the user was last updated

required
Array of objects

The user's identities

multifactor
Array of strings

The user's multifactor authentication methods

lastIp
string

The last IP address used by the user

lastLogin
string <date-time>

The date and time of the user's last login

loginsCount
integer

The number of times the user has logged in

Response samples

Content type
application/json
{
  • "bonterraAuthId": "string",
  • "email": "user@example.com",
  • "userMetadata": { },
  • "blocked": true,
  • "emailVerified": true,
  • "phoneNumber": "string",
  • "phoneVerified": true,
  • "username": "string",
  • "familyName": "string",
  • "givenName": "string",
  • "name": "string",
  • "nickname": "string",
  • "picture": "string",
  • "isBonterraGrants": false,
  • "userId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "identities": [
    ],
  • "multifactor": [
    ],
  • "lastIp": "string",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "loginsCount": 0
}

Delete a user from the Bonterra Auth by user id

Delete a user from the Bonterra Auth. The user id in the path is the user id.

Authorizations:
authorizer-lambdaapi_key
path Parameters
user_id
required
string

The ID of the user

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Update a user in the Bonterra Auth Service

Update a user in the Bonterra Auth Service. The user id in the path is the user id.

Authorizations:
authorizer-lambdaapi_key
path Parameters
user_id
required
string

The ID of the user

header Parameters
Content-Type
required
string
Default: application/json

Content type header

Request Body schema: application/json
required

User update request

bonterraAuthId
string

The unique identifier for the user in the Bonterra Auth.

email
string <email>

The user's email address

object

User metadata for the user

blocked
boolean

Whether the user is blocked

emailVerified
boolean

Whether the email has been verified. Passing in true will NOT send a user verification email.

phoneNumber
string

The user's phone number

phoneVerified
boolean

Whether the phone number has been verified

username
string

The user's username

familyName
string

The user's family name

givenName
string

The user's given name

name
string

The user's full name

nickname
string

The user's nickname

picture
string

The URL of the user's profile picture

isBonterraGrants
boolean
Default: false

Whether the user is a Bonterra grants user

verifyEmail
boolean
Default: false

Whether to send a verification email

verifyPhoneNumber
boolean
Default: false

Whether to send a verification SMS

password
string >= 8 characters

The user's password

clientId
string

The client ID to use for password hashing

passwordHash
string

The hashed password

passwordHashAlgorithm
string
Enum: "bcrypt" "pbkdf2" "argon2"

The algorithm used to hash the password

passwordHashSalt
string

The salt used for password hashing

passwordHashRounds
integer

The number of rounds used for password hashing

passwordHashMemory
integer

The memory cost for Argon2 password hashing

passwordHashParallelism
integer

The parallelism factor for Argon2 password hashing

passwordHashLength
integer

The length of the password hash

passwordHashFunction
string
Enum: "sha1" "sha256" "sha512"

The function used for PBKDF2 password hashing

Responses

Response Schema: application/json
bonterraAuthId
string

The unique identifier for the user in the Bonterra Auth.

email
required
string <email>

The user's email address

object

User metadata for the user

blocked
boolean

Whether the user is blocked

emailVerified
required
boolean

Whether the email has been verified. Passing in true will NOT send a user verification email.

phoneNumber
string

The user's phone number

phoneVerified
boolean

Whether the phone number has been verified

username
string

The user's username

familyName
string

The user's family name

givenName
string

The user's given name

name
string

The user's full name

nickname
string

The user's nickname

picture
string

The URL of the user's profile picture

isBonterraGrants
boolean
Default: false

Whether the user is a Bonterra grants user

userId
required
string

The unique identifier for the user

createdAt
required
string <date-time>

The date and time when the user was created

updatedAt
required
string <date-time>

The date and time when the user was last updated

required
Array of objects

The user's identities

multifactor
Array of strings

The user's multifactor authentication methods

lastIp
string

The last IP address used by the user

lastLogin
string <date-time>

The date and time of the user's last login

loginsCount
integer

The number of times the user has logged in

Request samples

Content type
application/json
{
  • "bonterraAuthId": "string",
  • "email": "user@example.com",
  • "userMetadata": { },
  • "blocked": true,
  • "emailVerified": true,
  • "phoneNumber": "string",
  • "phoneVerified": true,
  • "username": "string",
  • "familyName": "string",
  • "givenName": "string",
  • "name": "string",
  • "nickname": "string",
  • "picture": "string",
  • "isBonterraGrants": false,
  • "verifyEmail": false,
  • "verifyPhoneNumber": false,
  • "password": "stringst",
  • "clientId": "string",
  • "passwordHash": "string",
  • "passwordHashAlgorithm": "bcrypt",
  • "passwordHashSalt": "string",
  • "passwordHashRounds": 0,
  • "passwordHashMemory": 0,
  • "passwordHashParallelism": 0,
  • "passwordHashLength": 0,
  • "passwordHashFunction": "sha1"
}

Response samples

Content type
application/json
{
  • "bonterraAuthId": "string",
  • "email": "user@example.com",
  • "userMetadata": { },
  • "blocked": true,
  • "emailVerified": true,
  • "phoneNumber": "string",
  • "phoneVerified": true,
  • "username": "string",
  • "familyName": "string",
  • "givenName": "string",
  • "name": "string",
  • "nickname": "string",
  • "picture": "string",
  • "isBonterraGrants": false,
  • "userId": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "identities": [
    ],
  • "multifactor": [
    ],
  • "lastIp": "string",
  • "lastLogin": "2019-08-24T14:15:22Z",
  • "loginsCount": 0
}

Clients

Client credential management operations

Get API clients

Retrieve a paginated list of API clients accessible to the authenticated user

Authorizations:
authorizer-lambdaapi_key
query Parameters
page
integer >= 1
Default: 1

Page number for pagination (1-indexed)

per_page
integer [ 1 .. 100 ]
Default: 50

Number of results per page

tenant_id
string

Filter by tenant ID

tenant_type
string
Enum: "APRICOT" "BONTERRA" "CONNECT" "EMAIL_SERVICES" "GRANTMAKER" "GRANTS" "NONE" "OPT_ASK_COLD_START"

Filter by tenant type

status
string
Enum: "Active" "Disabled" "Locked" "Revoked"

Filter by client status

sort
string
Default: "desc"
Enum: "asc" "desc"

Sort order by creation date (ascending or descending)

Responses

Response Schema: application/json
required
Array of objects (Client)

Array of client objects

required
object

Pagination information

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Create a new API client

Create a new OAuth2 client for API access

Authorizations:
authorizer-lambdaapi_key
header Parameters
Content-Type
required
string
Default: application/json

Content type header

Request Body schema: application/json
required

Client creation request

clientName
required
string [ 3 .. 100 ] characters

Human-readable name for the client

clientDescription
string <= 500 characters

Optional description of the client's purpose

required
Array of objects (Tenant) = 1 items

Tenants to associate with this client. Currently limited to 1 tenant per client.

clientScopes
Array of strings

Optional list of scopes to grant to this client. If not provided, all available scopes for the tenant type will be automatically granted.

oauthGrantType
string
Default: "client_credentials"
Enum: "client_credentials" "authorization_code"

OAuth 2.0 grant type

tokenValidityInMins
integer [ 5 .. 1440 ]
Default: 300

Access token validity in minutes

refreshTokenDurationInMins
integer [ 60 .. 525600 ]
Default: 720

Absolute maximum lifetime of the refresh token in minutes. The refresh token will expire after this duration regardless of usage. Only applicable for authorization_code grant type.

refreshTokenIdleLifetimeInMins
integer [ 30 .. 43200 ]
Default: 240

Inactivity timeout for the refresh token in minutes. The refresh token will expire if not used within this duration. Only applicable for authorization_code grant type.

callbackUrls
Array of strings <uri> [ items <uri > ]

Required if oauthGrantType is authorization_code

logoutUrls
Array of strings <uri> [ items <uri > ]

Allowed logout URLs (for authorization_code only)

object

Optional metadata to attach to the client

Responses

Response Schema: application/json
clientId
required
string

The unique identifier for the client

clientName
required
string

The name of the client.

clientDescription
string

The description of the client.

oauthGrantType
required
string
Default: "client_credentials"
Enum: "client_credentials" "authorization_code"

OAuth 2.0 grant type

refreshTokenDurationInMins
integer

Absolute maximum lifetime of the refresh token in minutes. The refresh token will expire after this duration regardless of usage. Only applicable for authorization_code grant type.

refreshTokenIdleLifetimeInMins
integer

Inactivity timeout for the refresh token in minutes. The refresh token will expire if not used within this duration. Only applicable for authorization_code grant type.

tokenValidityInMins
integer

Access token validity in minutes

callbackUrls
Array of strings <uri> [ items <uri > ]

Allowed callback URLs (for authorization_code grant type)

logoutUrls
Array of strings <uri> [ items <uri > ]

Allowed logout URLs (for authorization_code grant type)

object

Additional client metadata

clientScopes
required
Array of strings

List of scopes granted to this client

required
Array of objects (Tenant)

The tenants that this app client is associated with.

status
required
string
Enum: "Active" "Disabled" "Locked" "Revoked"

Current client status

createdAt
required
string <date-time>

The datetime in which this entry was created.

updatedAt
string <date-time>

The datetime in which the entry was last modified.

bonterraAuthId
required
string

The Bonterra user ID

clientSecret
required
string

Client secret - ONLY returned on creation. Save immediately.

Request samples

Content type
application/json
{
  • "clientName": "My Integration",
  • "clientDescription": "Custom dashboard for analytics",
  • "tenants": [
    ],
  • "clientScopes": [
    ],
  • "oauthGrantType": "client_credentials",
  • "tokenValidityInMins": 300,
  • "refreshTokenDurationInMins": 720,
  • "refreshTokenIdleLifetimeInMins": 240,
  • "callbackUrls": [],
  • "logoutUrls": [],
  • "clientMetadata": {
    }
}

Response samples

Content type
application/json
{
  • "clientId": "abc123xyz789",
  • "clientName": "string",
  • "clientDescription": "Custom dashboard for analytics",
  • "oauthGrantType": "client_credentials",
  • "refreshTokenDurationInMins": 720,
  • "refreshTokenIdleLifetimeInMins": 240,
  • "tokenValidityInMins": 300,
  • "callbackUrls": [],
  • "logoutUrls": [],
  • "clientMetadata": {
    },
  • "clientScopes": [
    ],
  • "tenants": [
    ],
  • "status": "Active",
  • "createdAt": "2025-10-09T10:30:00Z",
  • "updatedAt": "2025-10-09T12:00:00Z",
  • "bonterraAuthId": "675d02b3-18a9-4a80-87e7-20dff82e2e03",
  • "clientSecret": "SECRET_xyz789_SAVE_THIS_NOW"
}

Delete a client

Delete an API client using one of two strategies:

  • Soft delete (default): rotate credentials, set Auth0 app metadata to inactive, and mark the DynamoDB record as inactive. Data is retained for audit and potential recovery.
  • Hard delete (?is_permanent=true): permanently remove the client from Auth0, delete the API Gateway key, remove all tenant mappings, and delete the DynamoDB record.
Authorizations:
authorizer-lambdaapi_key
path Parameters
client_id
required
string >= 10 characters

The unique identifier of the client

query Parameters
is_permanent
boolean
Default: false

When true, permanently deletes the client. When false (default), performs soft delete.

Request Body schema: application/json
optional

Optional deletion metadata

reason
string

Reason for deleting the client (used for soft delete audit trail)

Responses

Request samples

Content type
application/json
{
  • "reason": "Client requested account closure"
}

Response samples

Content type
application/json
{
  • "error": "string"
}

Connections

Enterprise connection management operations

Create a self-service SSO ticket

Generate a self-service profile ticket for enterprise connections. This endpoint allows customers to create SSO tickets that enable their enterprise customers to set up SSO connections through a self-service assistant.

The endpoint will:

  1. Retrieve the self-service profile ID (if profile_name is provided instead of profile_id)
  2. Create an SSO ticket using the Auth0 Management API

The SSO ticket URL can then be shared with customer admins to configure their SSO connection.

Authorizations:
authorizer-lambdaapi_key
header Parameters
Content-Type
required
string
Default: application/json

Content type header

Request Body schema: application/json
required

SSO ticket creation request

One of
profileId
required
string

The ID of the self-service profile. Either profileId or profileName must be provided.

profileName
string

The name of the self-service profile. Either profileId or profileName must be provided.

connectionId
string

ID of existing connection to modify (for editing existing connections)

object

Configuration for the connection that will be created

object

Configuration for domain aliases and verification

enabledClients
Array of strings

List of application/client IDs to enable for this connection

Array of objects

List of organizations to enable for this connection

ttlSec
integer [ 1 .. 2592000 ]
Default: 432000

Time to live for the SSO ticket in seconds (how long the URL is valid before being opened)

Responses

Response Schema: application/json
ticket
required
string

The SSO ticket ID that can be used to access the self-service assistant

Request samples

Content type
application/json
{
  • "profileId": "ssp_abc123xyz",
  • "profileName": "Enterprise SSO Profile",
  • "connectionId": "conn_abc123",
  • "connectionConfig": {
    },
  • "domainAliasesConfig": {
    },
  • "enabledClients": [
    ],
  • "enabledOrganizations": [
    ],
  • "ttlSec": 432000
}

Response samples

Content type
application/json
{
  • "ticket": "ticket_abc123xyz"
}

Endpoint POST access key and secret key. If successful, returns an OAuth token.

(Deprecated) This endpoint is used to generate an OAuth token by redirecting the request to Cognito's token endpoint. The result will be cached for ${token_endpoint_cache_ttl} seconds based on a combination of the client_id, client_secret, and scope.

header Parameters
Content-Type
required
string
Default: application/json

Content type header

Request Body schema: application/json
required

Token request

grant_type
required
string

The grant type of the token request. Accepted values are 'client_credentials', 'authorization_code' and 'refresh_token'.

client_id
string

The client id provided by the Bonterra API application.

client_secret
string

The client secret provided by the Bonterra API application.

audience
string

Required parameter that identifies the API you want to access. Use the API origin (https://api.bonterra.network) as the audience value.

scope
string

The scope of the token request.

redirect_uri
string

The redirect uri provided by the Bonterra API application, this is used for standalone management API.

refresh_token
string

The refresh token provided by the Bonterra API application.

code
string

The authorization code returned by the /authorize call.

code_verifier
string

The code verifier provided by the Bonterra API application (for PKCE).

Responses

Response Schema: application/json
access_token
required
string

The access token issued by the authorization server.

expires_in
required
string

The lifetime in seconds of the access token.

token_type
required
string

The type of the token issued.

refresh_token
string

The refresh token issued by the authorization server.

id_token
string

The id token issued by the authorization server.

Request samples

Content type
application/json
{
  • "grant_type": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "audience": "string",
  • "scope": "string",
  • "redirect_uri": "string",
  • "refresh_token": "string",
  • "code": "string",
  • "code_verifier": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": "string",
  • "token_type": "string",
  • "refresh_token": "string",
  • "id_token": "string"
}

Redirects users to the authorization endpoint with query parameters for OAuth authorization flow.

query Parameters
response_type
required
string
Example: response_type=code
client_id
required
string
redirect_uri
required
string
state
required
string
scope
string
Example: scope=openid profile email offline_access
audience
string
code_challenge
string
code_challenge_method
string
Value: "S256"
screen_hint
string
Value: "signup"
prompt
string
Value: "login"
header Parameters
Content-Type
required
string
Default: application/json

Content type header

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Introspection endpoint to get client info [WIP]

The introspection endpoint enables clients to request information about tokens that were issued to them. This endpoint is useful for providing information to the client about the tokens that were issued to them. [WIP]

Authorizations:
authorizer-lambdaapi_key
header Parameters
Content-Type
required
string
Default: application/json

Content type header

Authorization
required
string

Header that carries token for request Authorization

Responses

Response Schema: application/json
clientId
string
credentialState
string
Array of objects (ApricotUser)

Response samples

Content type
application/json
{
  • "clientId": "string",
  • "credentialState": "string",
  • "tenantDataList": [
    ]
}

Get user information from the User Profile API

Authorizations:
authorizer-lambdaapi_key

Responses

Response Schema: application/json
bonterraAuthId
string

The unique identifier for the user in the Bonterra Auth.

name
string

The user's full name

givenName
string

The user's given name

familyName
string

The user's family name

middleName
string

The user's middle name

nickname
string

The user's nickname

preferredUsername
string

The user's preferred username

profile
string

URL of the user's profile page

picture
string

URL of the user's profile picture

website
string

URL of the user's website

email
required
string <email>

The user's email address

emailVerified
boolean

Whether the user's email has been verified

gender
string

The user's gender

birthdate
string

The user's birth date

zoneinfo
string

The user's time zone

locale
string

The user's locale

phoneNumber
string

The user's phone number

phoneNumberVerified
boolean

Whether the user's phone number has been verified

object

The user's address information

updatedAt
string <date-time>

The time when the user's information was last updated

Response samples

Content type
application/json
{
  • "bonterraAuthId": "string",
  • "name": "John Doe",
  • "givenName": "John",
  • "familyName": "Doe",
  • "middleName": "Robert",
  • "nickname": "Johnny",
  • "preferredUsername": "johndoe",
  • "profile": "https://example.com/johndoe",
  • "picture": "https://example.com/johndoe.jpg",
  • "website": "https://johndoe.com",
  • "email": "john.doe@example.com",
  • "emailVerified": true,
  • "gender": "male",
  • "birthdate": "1990-01-01",
  • "zoneinfo": "America/Los_Angeles",
  • "locale": "en-US",
  • "phoneNumber": "+1 (555) 555-5555",
  • "phoneNumberVerified": true,
  • "address": {
    },
  • "updatedAt": "2024-03-20T12:00:00Z"
}

Revoke refresh token with Bonterra.

header Parameters
Content-Type
required
string
Default: application/json

Content type header

Request Body schema: application/json
required

Revoke refresh token

client_id
required
string

The client id provided by the Bonterra API application.

client_secret
required
string

The client secret provided by the Bonterra API application.

token
required
string

The refresh token provided by the Bonterra API application.

Responses

Response Schema: application/json
access_token
required
string

The access token issued by the authorization server.

expires_in
required
string

The lifetime in seconds of the access token.

token_type
required
string

The type of the token issued.

refresh_token
string

The refresh token issued by the authorization server.

id_token
string

The id token issued by the authorization server.

Request samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string",
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": "string",
  • "token_type": "string",
  • "refresh_token": "string",
  • "id_token": "string"
}

End user's single sign-in session with Bonterra.

query Parameters
returnTo
required
string <uri>

URL to redirect the user to after logout

client_id
required
string

The application's Client ID

Responses

Response samples

Content type
application/json
{
  • "error": "string"
}

Get users from the Bonterra Auth Service

Get users from the Bonterra Auth Service

Authorizations:
authorizer-lambdaapi_key
query Parameters
q
string

Search query using Lucene query syntax

per_page
integer
Default: 50

Number of results per page

connection
string

Connection filter

fields
string

Fields to include or exclude

has_fields
boolean
Default: true

Whether to include fields

is_primary_order
boolean
Default: false

Is primary order

search_engine
string
Default: "v2"
Enum: "v1" "v2" "v3"

The version of the search engine to use

sort
string

Field to sort by

page
number

Page number

Responses

Response Schema: application/json
Array
bonterraAuthId
string

The unique identifier for the user in the Bonterra Auth.

email
required
string <email>

The user's email address

object

User metadata for the user

blocked
boolean

Whether the user is blocked

emailVerified
required
boolean

Whether the email has been verified. Passing in true will NOT send a user verification email.

phoneNumber
string

The user's phone number

phoneVerified
boolean

Whether the phone number has been verified

username
string

The user's username

familyName
string

The user's family name

givenName
string

The user's given name

name
string

The user's full name

nickname
string

The user's nickname

picture
string

The URL of the user's profile picture

isBonterraGrants
boolean
Default: false

Whether the user is a Bonterra grants user

userId
required
string

The unique identifier for the user

createdAt
required
string <date-time>

The date and time when the user was created

updatedAt
required
string <date-time>

The date and time when the user was last updated

required
Array of objects

The user's identities

multifactor
Array of strings

The user's multifactor authentication methods

lastIp
string

The last IP address used by the user

lastLogin
string <date-time>

The date and time of the user's last login

loginsCount
integer

The number of times the user has logged in

Response samples

Content type
application/json
[
  • {
    }
]