Skip to content

Authentication

All API requests must include a valid API token. Permission Assist uses Bearer token authentication to verify API calls.

How authentication works

Every API request must include an Authorization header with a valid Bearer token. Permission Assist validates the token on each request and rejects calls with missing, invalid, or expired tokens.

  • Header format: Authorization: Bearer <your-token>
  • Scope: Tokens are system-wide. A valid token grants access to all API endpoints
  • Expiration: Tokens can optionally have an expiration date set at creation. After that date, the token stops working
  • Last-used tracking: Permission Assist updates a last-used timestamp on the token each time it is used to authenticate a request. You can view this timestamp on the token management page

When authentication fails, the API returns 401 Unauthorized with a JSON error body:

{
  "error": "unauthorized",
  "message": "Invalid or expired authentication token",
  "correlationId": "a1b2c3d4e5f67890abcdef1234567890"
}

Refer to Error codes for the complete error format.

Example request

curl -X GET https://[your-pa-server]/api/identities \
  -H "Authorization: Bearer pa_abc123def456..."

Generate credentials

Refer to Getting started — Step 2: Generate an API token for instructions on creating API tokens.

Manage credentials

Administrators manage API tokens at System Configuration > API Tokens.

  • View tokens: The token list displays each token's name, created date, expiration date, and last-used date
  • Delete a token: Select a token and select the Delete button Deletion is immediate — any system using that token loses access as soon as the token is deleted

Note

Token secrets cannot be viewed after creation. If you lose a token secret, delete the token and create a new one.

Security best practices

  • Store token secrets securely. Do not hard-code tokens in scripts that are stored in version control
  • Use a unique token for each automation tool or integration. This makes it easier to identify the source of API calls in audit logs and to revoke access for a single integration without affecting others
  • Set an expiration date on tokens when your security policy requires periodic credential rotation. When a token expires, delete it and create a new one
  • Review the token list periodically and delete tokens that are no longer in use. The last-used timestamp helps identify inactive tokens