Authentication

The REST API authenticates with OAuth 2.0 bearer tokens. A client exchanges its per-tenant API token for a short-lived signed JWT at the /token endpoint, then presents that JWT on every request. This grant lets server-to-server integrations authenticate without any interactive user sign-in.

POST https://identity.jonasapp.com/token

OAuth 2.0 · grant_type urn:jonas:api_token

Token request

Send an application/x-www-form-urlencoded POST to https://identity.jonasapp.com/token with the custom grant type. The request exchanges a per-tenant static token (provisioned by Jonas) for a JWT.

POST https://identity.jonasapp.com/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:jonas:api_token
&client_id=<client-id>
&token=<api-token>
&user=<optional-username>

Parameter	Description
`grant_type`	Required. Must be `urn:jonas:api_token`.
`client_id`	Required. The client ID.
`token`	Required. The per-tenant API token issued by Jonas for the application.
`user`	Optional. A Jonas username. When supplied, the issued token carries that user's identity. When omitted, the system identity `GJSYSTEM` is used.

Token response

On success the endpoint returns a signed JWT access token. Present it on subsequent requests in the Authorization header.

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

The token lifetime follows the service-wide configured lifespan. No refresh token is issued — callers re-exchange their API token when the access token expires.

Token claims

The issued JWT carries a minimal claim set scoped to API access. The jpt claim marks the token as an API principal, which downstream REST endpoints validate alongside the caller's API license.

Claim	Value
`sub`	The authenticated Jonas username, or `GJSYSTEM` when no `user` was supplied.
`name`	The user's full name, or `GJSYSTEM` for the system identity.
`aud`	The `client_id` from the token request.
`jun`	The username, or `GJSYSTEM`.
`jci`	The account code resolved from the client registration.
`jpt`	`user_api` — marks the token as an API principal.

User vs. system identity

With user: the username is combined with the tenant account code, validated against the tenant's active users, and the token is issued with that user's identity.
Without user: the token is issued under the synthetic system identity GJSYSTEM. Use this for unattended, system-level integrations.

Errors

Token exchange failures return a standard OAuth invalid_grant error. The token is compared using a constant-time comparison to prevent timing attacks.

Condition	Result
Invalid or missing `token`	`invalid_grant`
`user` not found or inactive under the tenant	`invalid_grant`

{
  "error": "invalid_grant",
  "error_description": "The supplied API token is invalid."
}