Authentication

Authenticate a Roots client integration with a bearer access token, then create scoped API tokens for service access.

Base URL

Send UAT requests to:

https://api.uat.roots.finance

Sign in

Send an operator email address and password to POST /api/v1/client/auth/login.

{
  "email": "[email protected]",
  "password": "<your-password>"
}

Roots returns a session with an access token and refresh token.

{
  "status": "session_issued",
  "access_token": "<access-token>",
  "refresh_token": "<refresh-token>",
  "identity_id": "ident_123",
  "role": "admin"
}

Send the access token with authenticated client requests:

Authorization: Bearer <access-token>

Refresh an access token

Send the refresh token to POST /api/v1/client/auth/refresh before the access token expires.

{
  "refresh_token": "<refresh-token>"
}

Replace the stored access and refresh tokens with the values Roots returns. Do not log either token.

Create an API token

Create a scoped API token with POST /api/v1/client/api-tokens. This operation requires a bearer access token and an idempotency key.

Authorization: Bearer <access-token>
Idempotency-Key: <unique-key>
Content-Type: application/json

{
  "scope": "read_write",
  "module_scopes": ["accounts", "transfers"]
}

Roots returns the token only at creation.

{
  "id": "cred_123",
  "token": "<shown-once>",
  "scope": "read_write",
  "module_scopes": ["accounts", "transfers"],
  "created_at": "2026-08-05T14:00:00Z"
}

Manage sessions and tokens

Use these client endpoints to manage access:

Create a replacement API token, deploy it, and then revoke the old token. Use the least privilege available through scope and module_scopes.

Next steps

• Follow Quickstart to authenticate your first client request.
• Read Idempotency before creating resources or transfers.
• Read Security and data handling for credential-storage requirements.