Kobble Authorization API

Overview

The Authorization API provides a secure mechanism to obtain an access token using the OAuth 2.0 client credentials flow. This access token is required to authenticate API requests in the system.

Authentication

Every business endpoint requires two headers:

Header	Value
`Authorization`	`Bearer <access token>`
`x-client-id`	Your Kobble client identifier

The Bearer prefix is required. A token sent without it is rejected.

Request the access token from the Cognito host for your environment, not from the API host:

Environment	Token endpoint
Production	`https://cognito.apikobble.net/oauth2/token`
Staging	`https://cognito.staging.apikobble.net/oauth2/token`

Tokens are valid for 3600 seconds. The token response carries no refresh token, so request a new token before the current one expires.

Two endpoints need no authentication: GET /customers/v1/health and POST /oauth2/token.

When authentication fails:

401 — the access token is missing or invalid.

403 — the token is valid but is not authorised for this operation, for example a missing scope. A 403 raised by client identification carries an empty body, {}.

Base URLs

Use the appropriate base URL depending on the environment:

Production: https://apikobble.net/

Staging: https://staging.apikobble.net/

Ensure you prepend the base URL to each endpoint while making requests.

Each environment has its own Cognito user pool, so your staging client ID and secret will not authenticate against production. Production credentials are issued separately as part of go-live.

Endpoint

URL:
oauth2/token

Method:
POST

Content-Type:
application/x-www-form-urlencoded

Request Parameters

Parameter	Type	Required	Description
`grant_type`	string	Yes	OAuth 2.0 grant type. Must be `client_credentials`.
`client_id`	string	Yes	The client identifier issued during registration.
`client_secret`	string	Yes	The secret key associated with the client.
`scope`	string	Yes	The access scope. Options are:
			- `client/read`
			- `client/write`
			- `administrator/read`
			- `administrator/write`

Sample Request

Sample Response

Authorization API Notes and Error Codes

Notes

The access_token is a JWT used to authenticate subsequent API requests.

The token's lifespan is defined in the expires_in field (in seconds). A new token must be requested once it expires.

The scope determines the level of access granted. Use the following based on your needs:

Read-only access:

client/read

administrator/read

Write access:

client/write

administrator/write

Keep your client_secret secure and never expose it in your application code or client-side scripts.

Error Codes

Status Code	Description
`400`	Bad Request - Invalid parameters or missing data.
`401`	Unauthorized - Invalid credentials or token.
`403`	Forbidden - The client is not allowed access to the requested resource.
`500`	Internal Server Error - An issue occurred on the server.

Authorization

Kobble Authorization API#

Overview#

Authentication#

Base URLs#

Endpoint#

Request Parameters#

Sample Request#

Sample Response#

Authorization API Notes and Error Codes#

Notes#

Error Codes#