API docs by Redocly

Bonterra Auth API (1.0.0)

Download OpenAPI specification:

Chaos Team: chaos@bonterratech.com License: Proprietary

Authentication service for the Bonterra Network

This API provides OAuth2/OpenID Connect authentication, custom JWT claims, and user lifecycle event streams for the Bonterra ecosystem.

Authentication

OAuth2 and OpenID Connect endpoints

OpenID Connect Discovery

Get OpenID Connect discovery document containing metadata about the OAuth2/OpenID Connect provider configuration.

Authorizations:
BearerAuthClientCredentials

Responses

Response Schema: application/json
issuer
string
authorization_endpoint
string
token_endpoint
string
userinfo_endpoint
string
jwks_uri
string
revocation_endpoint
string
scopes_supported
Array of strings
response_types_supported
Array of strings
grant_types_supported
Array of strings

Response samples

Content type
application/json
{}

JSON Web Key Set

Get public keys used for JWT signature verification. These keys rotate periodically for security.

Authorizations:
BearerAuthClientCredentials

Responses

Response Schema: application/json
Array of objects

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

Authorization Endpoint

Initiate OAuth2/OpenID Connect authorization flow. Redirects user to Auth0 login page.

Authorizations:
BearerAuthClientCredentials
query Parameters
response_type
required
string
Enum: "code" "token" "id_token"
Example: response_type=code

OAuth2 response type

client_id
required
string
Example: client_id=abc123xyz789

Application client ID

redirect_uri
required
string <uri>
Example: redirect_uri=https://myapp.example.com/callback

Callback URL after authorization

scope
string
Example: scope=openid profile email

Requested scopes (space-separated)

state
string
Example: state=xyz123

State parameter for CSRF protection

audience
string
Example: audience=https://api.bonterra.network

Target API audience

nonce
string
Example: nonce=abc123

Nonce for ID token replay protection

Responses

Token Endpoint

Exchange authorization code, client credentials, or refresh token for access tokens. Returns JWT tokens with custom Bonterra claims.

Authorizations:
BearerAuthClientCredentials
Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Enum: "authorization_code" "client_credentials" "refresh_token"

OAuth2 grant type

client_id
required
string

Application client ID

client_secret
required
string

Application client secret

code
string

Authorization code (for authorization_code grant)

redirect_uri
string

Redirect URI (for authorization_code grant)

audience
string

Target API audience

scope
string

Requested scopes

refresh_token
string

Refresh token (for refresh_token grant)

Responses

Response Schema: application/json
access_token
string

JWT access token containing custom Bonterra claims:

  • urn:bonterra:claims:bonterra_auth_id (UUID)
  • urn:bonterra:claims:is_bonterra_grants (boolean)
id_token
string

JWT ID token with user information

refresh_token
string

Refresh token for getting new access tokens

token_type
string
expires_in
integer

Token lifetime in seconds

scope
string

Granted scopes

Request samples

Content type
application/x-www-form-urlencoded
Example
grant_type=authorization_code&client_id=abc123xyz789&client_secret=secret123&code=auth_code_123456&redirect_uri=https%3A%2F%2Fmyapp.example.com%2Fcallback&audience=https%3A%2F%2Fapi.bonterra.network

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.eyJpc3MiOiJodHRwczovL2F1dGguYm9udGVycmEubmV0d29yay8iLCJzdWIiOiJhdXRoMHw1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwMTEiLCJhdWQiOiJodHRwczovL2FwaS5ib250ZXJyYS5uZXR3b3JrIiwiZXhwIjoxNjcyNTMxMjAwLCJpYXQiOjE2NzI0NDQ4MDAsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgZW1haWwiLCJ1cm46Ym9udGVycmE6Y2xhaW1zOmJvbnRlcnJhX2F1dGhfaWQiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAiLCJ1cm46Ym9udGVycmE6Y2xhaW1zOmlzX2JvbnRlcnJhX2dyYW50cyI6dHJ1ZX0.signature_here",
  • "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.eyJpc3MiOiJodHRwczovL2F1dGguYm9udGVycmEubmV0d29yay8iLCJzdWIiOiJhdXRoMHw1MDdmMWY3N2JjZjg2Y2Q3OTk0MzkwMTEiLCJhdWQiOiJhYmMxMjN4eXo3ODkiLCJleHAiOjE2NzI1MzEyMDAsImlhdCI6MTY3MjQ0NDgwMCwibm9uY2UiOiJhYmMxMjMiLCJlbWFpbCI6InVzZXJAZXhhbXBsZS5jb20iLCJuYW1lIjoiSm9obiBEb2UiLCJ1cm46Ym9udGVycmE6Y2xhaW1zOmJvbnRlcnJhX2F1dGhfaWQiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAiLCJ1cm46Ym9udGVycmE6Y2xhaW1zOmlzX2JvbnRlcnJhX2dyYW50cyI6dHJ1ZX0.id_signature_here",
  • "refresh_token": "refresh_token_xyz123",
  • "token_type": "Bearer",
  • "expires_in": 86400,
  • "scope": "openid profile email"
}

Token Revocation

Revoke access or refresh tokens

Authorizations:
BearerAuthClientCredentials
Request Body schema: application/x-www-form-urlencoded
required
token
required
string

Token to revoke

client_id
required
string
client_secret
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "error": "invalid_request",
  • "error_description": "Missing required parameter: client_id"
}

User Information

Get user information using a valid access token. Returns user profile with custom Bonterra claims.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
sub
string

User ID

email
string <email>
email_verified
boolean
name
string
given_name
string
family_name
string
picture
string <uri>
updated_at
string <date-time>
urn:bonterra:claims:bonterra_auth_id
string <uuid>
urn:bonterra:claims:is_bonterra_grants
boolean

Response samples

Content type
application/json
{
  • "sub": "auth0|507f1f77bcf86cd799439011",
  • "email": "user@example.com",
  • "email_verified": true,
  • "name": "John Doe",
  • "given_name": "John",
  • "family_name": "Doe",
  • "picture": "https://example.com/avatar.jpg",
  • "updated_at": "2024-01-15T10:30:00.000Z",
  • "urn:bonterra:claims:bonterra_auth_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  • "urn:bonterra:claims:is_bonterra_grants": true
}

User Management

User lifecycle operations via Auth0 Management API

List Users

List users (Auth0 Management API)

Authorizations:
ClientCredentials
query Parameters
per_page
integer [ 1 .. 100 ]
Default: 25
Example: per_page=25

Number of results per page

page
integer >= 0
Default: 0

Page number (0-indexed)

q
string
Example: q=email:"user@example.com"

Search query using Lucene syntax. Examples:

Responses

Response Schema: application/json
Array of objects (User)
start
integer

Starting index

limit
integer

Number of results per page

length
integer

Total number of users

total
integer

Total count

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "start": 0,
  • "limit": 25,
  • "length": 2,
  • "total": 150
}

Get User

Get user by ID (Auth0 Management API)

Authorizations:
ClientCredentials
path Parameters
userId
required
string
Example: auth0|507f1f77bcf86cd799439011

Auth0 user ID

Responses

Response Schema: application/json
user_id
string
email
string <email>
email_verified
boolean
name
string
given_name
string
family_name
string
picture
string
created_at
string <date-time>
updated_at
string <date-time>
object

Bonterra-specific metadata

user_metadata
object

User-editable metadata

Response samples

Content type
application/json
{
  • "user_id": "auth0|507f1f77bcf86cd799439011",
  • "email": "user@example.com",
  • "email_verified": true,
  • "name": "John Doe",
  • "given_name": "John",
  • "family_name": "Doe",
  • "picture": "https://example.com/avatar.jpg",
  • "created_at": "2024-01-01T12:00:00.000Z",
  • "updated_at": "2024-01-15T10:30:00.000Z",
  • "app_metadata": {
    },
  • "user_metadata": {
    }
}

Update User

Update user metadata (Auth0 Management API)

Authorizations:
ClientCredentials
path Parameters
userId
required
string
Example: auth0|507f1f77bcf86cd799439011

Auth0 user ID

Request Body schema: application/json
required
email
string <email>
name
string
given_name
string
family_name
string
object
user_metadata
object

Responses

Response Schema: application/json
user_id
string
email
string <email>
email_verified
boolean
name
string
given_name
string
family_name
string
picture
string
created_at
string <date-time>
updated_at
string <date-time>
object

Bonterra-specific metadata

user_metadata
object

User-editable metadata

Request samples

Content type
application/json
{
  • "name": "John Updated Doe",
  • "app_metadata": {
    },
  • "user_metadata": {
    }
}

Response samples

Content type
application/json
{
  • "user_id": "auth0|507f1f77bcf86cd799439011",
  • "email": "user@example.com",
  • "email_verified": true,
  • "name": "John Doe",
  • "given_name": "John",
  • "family_name": "Doe",
  • "picture": "https://example.com/avatar.jpg",
  • "created_at": "2024-01-01T12:00:00.000Z",
  • "updated_at": "2024-01-15T10:30:00.000Z",
  • "app_metadata": {
    },
  • "user_metadata": {
    }
}

Event Streams

Real-time user event notifications

Health

Service health and monitoring