Issue access and refresh tokens using API key

POST 
/auth/tokens

Exchange an API key for access and refresh tokens.

Algorithm:

1. Hash API key with SHA-256
2. Search user in Keycloak by api_key_hash attribute
3. If found, get company_id from user's fortis.companies attribute
4. Get token-exchanger service account token from Keycloak
5. Perform token exchange (impersonation) with company_id to obtain company-scoped tokens
6. Return access_token + refresh_token to client

NOTE: This operation is duplicated in keycloak-client/openapi.yaml. Keep both in sync.

Request

application/json

Body

required

api_key stringrequired

Possible values: non-empty and <= 256 characters

The API key to authenticate the request

Responses

200

Tokens issued successfully

application/json

Schema

Schema

access_token stringrequired

Possible values: <= 8000 characters

The access token. It is possible to decrypt the token using https://www.jwt.io resource

refresh_token string

Possible values: <= 8000 characters

A credential used to obtain a new Access Token without requiring the user to re-authenticate, ensuring continuous access to protected resources.

token_type stringrequired

The type of the access token

expires_in int32

The lifetime of the access token, in seconds

refresh_expires_in int32

The lifetime of the refresh token, in seconds

Example (from schema)

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyS0VKSWU2RjgtRFByd1BKU3dSQXpTUGxtT3R3OUdJZXhrSWtTN2EwLWdFIn0.eyJleHAiOjE3NDQ3MDgyMzIsImlhdCI6MTc0NDcwNzkzMiwianRpIjoiNTcwYTA3MTMtY2YxZS00OTFiLTk1NDgtOTc2MDk4ZmU3ZjYwIiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay1kZXYuaHR0cC5kZXYuZm9ydGlzZHMudGVjaC9yZWFsbXMvZm9ydGlzIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImMxZDY0ODA1LTQyMmUtNDU2Yy1iNzg3LWRhNzJiMWU1YTVhNiIsInR5cCI6IkJlYXJlciIsImF6cCI6ImZvcnRpcy1iYWNrb2ZmaWNlIiwic2lkIjoiYjc1ZWQwY2UtMzUxOS00NWFkLThlOGYtNmQ5NDlkZjM5MGZlIiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwczovL215LWRldi5odHRwLmRldi5mb3J0aXNkcy50ZWNoIiwiKiIsImh0dHA6Ly9sb2NhbGhvc3Q6ODAwMCJdLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiZGVmYXVsdC1yb2xlcy1mb3J0aXMiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiZm9ydGlzLWJhY2tvZmZpY2UiOnsicm9sZXMiOlsiZm9ydGlzLWJhY2tvZmZpY2Utcm9sZSJdfSwiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJncm91cHMtbWFwcGVyIGZvcnRpcy1jb21wYW5pZXMgZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJmb3J0aXMiOnsiY29tcGFuaWVzIjpbeyJjb21wYW55X2lkIjoiOGU1M2ZiZTItMzgyZS00NGQ2LThiNTQtMTQ4NTY5OTgxMmI2Iiwicm9sZSI6Im93bmVyIiwiZW1wbG95ZWVfaWQiOiI0YmY0YzE0MC01MDFmLTQwNjctOTdjMS0wODUwYTJhYzMwY2MifV19LCJncm91cHMiOlsiOGU1M2ZiZTItMzgyZS00NGQ2LThiNTQtMTQ4NTY5OTgxMmI2Il0sInByZWZlcnJlZF91c2VybmFtZSI6Ijk3MTEyMzQ1NjAwMSIsImVtYWlsIjoibS5ncmFjaGV2Kzk3MTEyMzQ1NjAwMUBsaWZlLXBheS5ydSJ9.ePnztW1Ep38xiclUd73PeG-OrpDupjixP9Qb6MmsX66JH-szA218xiGG0aDS0G3ohRzjVuBEfQTgKr80HM2pcncNnmXfMnOUutBKEa36s0kPH4foOlDxhiQ8AUInzN2YFPDaV9Px6X2JmHnzI1OLFakR26cJSOCW4FxTgd5B1ggzQO1Cv-ZtzOabxXMo3n22uyxxHJC6wzPeHBZ8TOx32iF8xjxuXRg2NVVfWp9aB5xkMNBRgWjF9diiGm_bSxJW7uhyo2g31cnduYFihPiVV0voxuUkbMJOiJCW5-2t8-d2T2Iaq2pVo0Ao_IoaSy-nP0Wcm3uVeveXwbCBy8-A_A",
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJlZjk5ZGUxYy0zM2IzLTRmMzItYjkzOC02N2RjYzY5OGQ2MzQifQ.eyJleHAiOjE3NDQ3MTE1MzIsImlhdCI6MTc0NDcwNzkzMiwianRpIjoiYTFkZTkxMTMtM2NkMi00NDI2LWE2YTYtZWY3MGQxYWVlYWRjIiwiaXNzIjoiaHR0cHM6Ly9rZXljbG9hay1kZXYuaHR0cC5kZXYuZm9ydGlzZHMudGVjaC9yZWFsbXMvZm9ydGlzIiwiYXVkIjoiaHR0cHM6Ly9rZXljbG9hay1kZXYuaHR0cC5kZXYuZm9ydGlzZHMudGVjaC9yZWFsbXMvZm9ydGlzIiwic3ViIjoiYzFkNjQ4MDUtNDIyZS00NTZjLWI3ODctZGE3MmIxZTVhNWE2IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImZvcnRpcy1iYWNrb2ZmaWNlIiwic2lkIjoiYjc1ZWQwY2UtMzUxOS00NWFkLThlOGYtNmQ5NDlkZjM5MGZlIiwic2NvcGUiOiJncm91cHMtbWFwcGVyIHJvbGVzIGZvcnRpcy1jb21wYW5pZXMgYWNyIHdlYi1vcmlnaW5zIGVtYWlsIGJhc2ljIHByb2ZpbGUifQ.VOgKrkOa_7-1hrUAejp7V9lhTh9D5Jm12CxjHNt9uKK3dkYXFaBCvkcHcDkib1h-O9KNRyLZ7XcNaMoSIoIm1A",
  "token_type": "Bearer",
  "expires_in": 300,
  "refresh_expires_in": 1800
}

400

Invalid or missing API key

application/json

Schema

Schema

title stringrequired

A short summary of the problem

type stringnullable

A URI reference RFC3986 that identifies the problem type.

errors objectnullable

Problem type definition

detail stringnullable

An explanation of the problem

trace_id stringnullable

An identification number used for error reporting or investigation

code stringnullable

A string error code used by the frontend to display a user-friendly message or to make decisions based on the error

status integernullable

HTTP status code; matches the response status

reason stringnullable

Machine-readable sub-reason qualifying the top-level code (e.g. duplicate_external_data_id for an existing_entity_conflict)

Example (from schema)

{
  "title": "One or more validation errors occurred",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "errors": "{\"name\": [\"The name field is required.\"]}",
  "detail": "No matching discount",
  "trace_id": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00",
  "code": "inconsistent_order_state",
  "status": 409,
  "reason": "duplicate_external_data_id"
}

Invalid Request

{
  "title": "Invalid Request",
  "code": "invalid_request",
  "status": 400
}

401

API key not found or invalid

application/json

Schema

Schema

title stringrequired

A short summary of the problem

type stringnullable

A URI reference RFC3986 that identifies the problem type.

errors objectnullable

Problem type definition

detail stringnullable

An explanation of the problem

trace_id stringnullable

An identification number used for error reporting or investigation

code stringnullable

A string error code used by the frontend to display a user-friendly message or to make decisions based on the error

status integernullable

HTTP status code; matches the response status

reason stringnullable

Machine-readable sub-reason qualifying the top-level code (e.g. duplicate_external_data_id for an existing_entity_conflict)

Example (from schema)

{
  "title": "One or more validation errors occurred",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "errors": "{\"name\": [\"The name field is required.\"]}",
  "detail": "No matching discount",
  "trace_id": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00",
  "code": "inconsistent_order_state",
  "status": 409,
  "reason": "duplicate_external_data_id"
}

Invalid Token

{
  "title": "Invalid Token",
  "code": "invalid_token",
  "status": 401
}

Access Denied

{
  "title": "Access Denied",
  "code": "access_denied",
  "status": 401
}

500

Keycloak service error

application/json

Schema

Schema

title stringrequired

A short summary of the problem

type stringnullable

A URI reference RFC3986 that identifies the problem type.

errors objectnullable

Problem type definition

detail stringnullable

An explanation of the problem

trace_id stringnullable

An identification number used for error reporting or investigation

code stringnullable

A string error code used by the frontend to display a user-friendly message or to make decisions based on the error

status integernullable

HTTP status code; matches the response status

reason stringnullable

Machine-readable sub-reason qualifying the top-level code (e.g. duplicate_external_data_id for an existing_entity_conflict)

Example (from schema)

{
  "title": "One or more validation errors occurred",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "errors": "{\"name\": [\"The name field is required.\"]}",
  "detail": "No matching discount",
  "trace_id": "00-84c1fd4063c38d9f3900d06e56542d48-85d1d4-00",
  "code": "inconsistent_order_state",
  "status": 409,
  "reason": "duplicate_external_data_id"
}

Loading...