Authentication APIs

The Authentication APIs allow you to generate temporary access tokens for use with all other BizzAssure APIs.

Generate Token

Create a temporary access token using your API credentials.

Endpoint

POST /v1/auth/token

Request

Headers

Header	Value
Content-Type	application/json

Body

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "scopes": ["employee.get", "policy.list"]
}

Fields

Field	Type	Required	Description
client_id	string	Yes	Your API access key provided by BizzAssure
client_secret	string	Yes	Your API secret access key provided by BizzAssure
scopes	string[]	Yes	List of permission scopes to grant to the token (see Scopes below)

Scope names are case-insensitive and accept . as a separator (for example, employee.get and EMPLOYEE_GET are equivalent).

Available Scopes

Scope	Description
employee.get	Read a single employee's profile
employee.create	Create new employees
employee.update	Update an existing employee
employee.all	Full access to all employee operations
policy.get	Read a single policy
policy.list	List policies
policy.members.list	List members of a policy
policy.all	Full access to all policy operations

Response

Success (200 OK)

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

Response Fields

Field	Type	Description
access_token	string	JWT token to be included in the Authorization header
expires_in	number	Token lifetime in seconds (always 3600)
token_type	string	Always "Bearer"

Error Responses

Invalid Credentials (401 Unauthorized)

{
  "type": "A4001",
  "title": "Invalid Authentication Credentials",
  "detail": "The provided client_id or client_secret is invalid",
  "instance": "/v1/auth/token"
}

Rate Limit Exceeded (429 Too Many Requests)

{
  "type": "A4290",
  "title": "Rate Limit Exceeded",
  "detail": "Too many token requests. Please try again in 60 seconds",
  "instance": "/v1/auth/token"
}

Unexpected Error (500 Internal Server Error)

{
  "type": "E5000",
  "title": "An unexpected error occurred",
  "detail": "",
  "instance": "/v1/auth/token"
}

Error Response Fields

Field	Type	Description
type	string	Error code (e.g., "A4001")
title	string	Brief error description
detail	string	Detailed error message
instance	string	API endpoint where error occurred

---

Using the Token

Include the token in the Authorization header of all subsequent API requests:

Authorization: Bearer YOUR_TOKEN

Token Lifecycle

• Tokens are valid for 1 hour from the time of creation.
• You can generate a new token at any time before expiry.
• Tokens cannot be refreshed — generate a new one when it expires.
• Each client is limited to 100 token generations per hour.

Security Best Practices

1. Store credentials securely — never hardcode client_id or client_secret in source code. Use environment variables or a secrets manager.
2. Rotate credentials regularly — contact BizzAssure support to rotate your client_secret.
3. Request only the scopes you need — follow the principle of least privilege when listing scopes.
4. Never expose tokens client-side — tokens should only be used in server-to-server calls.