Request an access token

POST /auth/api-token

Request an access token to begin interacting with the TrueIdentity API

Request body

Content type application/json

Fields

Field	Type	Required	Description
`client_id`	string	yes
`client_secret`	string	yes

Example request body

{
  "client_id": "string",
  "client_secret": "string"
}

Responses

Status	Description
`200 OK`	Access token retrieved successfully
`400 Bad Request`	Invalid client credentials
`401 Unauthorized`	Authentication failed or invalid token
`403 Forbidden`	Unauthorized or insufficient permissions
`429 Too Many Requests`	Too many requests
`500 Internal Server Error`	Internal server error

Content type application/json

TokenResponse (200)

Field	Type	Required	Description
`access_token`	string	no	JWT access token for API authentication
`refresh_token`	string	no	Token that can be used to obtain a new access token
`expires_in`	integer	no	Time in seconds until the token expires
`expires`	string	no	RFC 2822 formatted date when the token expires

Example 200 response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjM4MmE0YTE0In0.eyJzdWIiOiJjNTVhYjY5NC03Nzc5LTQwZjctYmIyMy01YzYxNDNjMmVmMDMiLCJ0ZW5hbnRJZCI6IjA0OGMyYTFjLTA4ODEtNGRjYy1iZmNhLTZlMzE4MDIwNzU1MSIsInJvbGVzIjpbIkFkbWluIl0sInBlcm1pc3Npb25zIjpbImZlLnNlY3VyZS4qIiwiZmUuY29ubmVjdGl2aXR5LioiLCJmZS5hY2NvdW50LXNldHRpbmdzLnJlYWQuYXBwIl0sIm1ldGFkYXRhIjp7fSwiY3JlYXRlZEJ5VXNlcklkIjoiNzZjOTJjMWItNDVmMS00NGJhLWE4M2YtYzliNDM2ZGVlNGVjIiwidHlwZSI6InRlbmFudEFwaVRva2VuIiwiYXBwbGljYXRpb25JZCI6ImQyZjcyZjc1LTJkZmQtNDYyMy04OTgwLTJjYzI4ZDVhNzhlNSIsImF1ZCI6IjM4MmE0YTE0LWUzZDEtNDI1MS1hNTc3LWYxMGI4ZmI4YmViMCIsImlzcyI6Imh0dHBzOi8vdHJ1ZS1zYW5kYm94LmF1LmZyb250ZWdnLmNvbSIsImlhdCI6MTc0ODQ3ODg2NSwiZXhwIjoxNzQ4NTY1MjY1fQ.Bc3ovyOyDqtCF-LNOS86JV_WPUkKAlY59SSYG8979DzZRJ4sABv_5FyY2DUk4zkOuucLVRv2Fd7DVoq8VV8aZm45MqPbdmhGZ68TUyGY5ZNLRPbyzdwLqEWA5T2uMwVuQzmfv3RidomGid6Yke0-QEe9RjffsV_LRIgM_eVaSNOc7jYA5oQu3RqsiadsiyWUAE9EPQJ0imjqUCaA8IJQVWjmbuEF_wa5pJcAuknp0HGb1_pzS_cpragkwvZpfNugXP58sa0bO1DA4b4CY6rbiKnm-4OaY3PXYGzs_oD_otEkBKTw6BRLclBSXiSXuEleOdrqZxYmPMCZo1BVkJvS2Q",
  "refresh_token": "67c08c7b-1c78-4021-a026-896a03c63e64",
  "expires_in": 86400,
  "expires": "Fri, 30 May 2025 00:34:25 GMT"
}

Content type application/json

ErrorResponse (400)

Field Type Required Description

error

object

yes

Every error carries a machine-readable type and a code. Match on one of these rather than on the message, which is written for people and may change.

Code	Type	HTTP
`E1001`	`VALIDATION_ERROR`	400
`E1002`	`INVALID_REQUEST`	400
`E1003`	`AUTHENTICATION_FAILED`	401
`E1004`	`UNAUTHORIZED`	403
`E1005`	`NOT_FOUND`	404
`E1006`	`CONFLICT`	409
`E1007`	`RATE_LIMIT_EXCEEDED`	429
`E1008`	`PRECONDITION_FAILED`	412
`E1009`	`CREDENTIAL_EXPIRED`	412
`E1010`	`CREDENTIAL_REVOKED`	412
`E1011`	`CREDENTIAL_PENDING_ACCEPTANCE`	412
`E1012`	`CREDENTIAL_VERIFICATION_FAILED`	412
`E2001`	`INTERNAL_ERROR`	500
`E2002`	`INTERNAL_ERROR_EMAIL`	500
`E2003`	`DATABASE_ERROR`	500
`E2004`	`EXTERNAL_SERVICE_ERROR`	502
`E2005`	`SERVICE_UNAVAILABLE`	503

error.message

string

yes

Human readable error message

error.type

string

yes

Error type identifier

One of: VALIDATION_ERROR, INVALID_REQUEST, AUTHENTICATION_FAILED, UNAUTHORIZED, NOT_FOUND, CONFLICT, RATE_LIMIT_EXCEEDED, PRECONDITION_FAILED, CREDENTIAL_EXPIRED, CREDENTIAL_REVOKED, CREDENTIAL_PENDING_ACCEPTANCE, CREDENTIAL_VERIFICATION_FAILED, INTERNAL_ERROR, INTERNAL_ERROR_EMAIL, DATABASE_ERROR, EXTERNAL_SERVICE_ERROR, SERVICE_UNAVAILABLE

error.code

string

yes

Machine-readable error code

One of: E1001, E1002, E1003, E1004, E1005, E1006, E1007, E1008, E1009, E1010, E1011, E1012, E2001, E2002, E2003, E2004, E2005

error.timestamp string yes

error.correlation_id string yes

error.details

object

Additional error context

Example 400 response

{
  "error": {
    "message": "string",
    "type": "VALIDATION_ERROR",
    "code": "E1001",
    "timestamp": "2026-02-20T03:14:15Z",
    "correlation_id": "string"
  }
}

Content type application/json

Response fields (401)

Field	Type	Required	Description
`error`	object	yes

Example 401 response

{
  "error": {
    "type": "AUTHENTICATION_FAILED",
    "code": "E1003"
  }
}

Content type application/json

Response fields (403)

Field	Type	Required	Description
`error`	object	yes

Example 403 response

{
  "error": {
    "type": "UNAUTHORIZED",
    "code": "E1004"
  }
}

Content type application/json

Response fields (429)

Field	Type	Required	Description
`error`	object	yes

Example 429 response

{
  "error": {
    "type": "RATE_LIMIT_EXCEEDED",
    "code": "E1007"
  }
}

Content type application/json

Response fields (500)

Field	Type	Required	Description
`error`	object	yes

Example 500 response

{
  "error": {
    "type": "INTERNAL_ERROR",
    "code": "E2001"
  }
}

Example request

curl --request POST \
  --url https://api.sandbox.truevault.com.au/api/v1/auth/api-token \
  --header 'Content-Type: application/json'