Quickstart

Create a front-office session and generate an API key for your Roots company.

Before you begin

• Obtain a front-office user email address and password from your Roots administrator.
• Confirm that your user can generate API keys. Roots returns 403 Forbidden when your role is not permitted to create one.
• Store secrets in a secret manager. Roots shows an API-key secret only when you create the key.

API base URL

Send UAT API requests to:

https://api.uat.roots.finance

1. Sign in to the front office

Send your front-office user credentials to POST https://api.uat.roots.finance/frontoffice/auth/login.

A successful response returns the signed-in user, including their company ID, role, and status.

{
  "user": {
    "id": "user_123",
    "companyId": "company_123",
    "email": "[email protected]",
    "scope": "FRONT_OFFICE",
    "roleKey": "COMPANY_ADMIN",
    "status": "ACTIVE",
    "createdAt": "2026-08-03T10:00:00Z",
    "updatedAt": "2026-08-03T10:00:00Z",
    "lastLoginAt": "2026-08-03T10:00:00Z"
  }
}

If the credentials are invalid, Roots returns 401 Unauthorized with an error message.

{
  "error": "Invalid credentials"
}

2. Generate an API key

Create a key for the caller's company with POST https://api.uat.roots.finance/frontoffice/api-keys.

{
  "label": "production-payments-service",
  "roleKey": "OPERATOR"
}

Roots returns the key record and its secret when it creates the key.

{
  "apiKey": {
    "id": "key_123",
    "companyId": "company_123",
    "label": "production-payments-service",
    "roleKey": "OPERATOR",
    "status": "ACTIVE",
    "lastUsedAt": null,
    "createdByUserId": "user_123",
    "createdAt": "2026-08-03T10:05:00Z",
    "secret": "<shown-once>"
  }
}

3. Verify the session

Call GET https://api.uat.roots.finance/frontoffice/auth/me to retrieve the current front-office session. Confirm that the returned user has status: ACTIVE and belongs to the intended company before you continue.

What’s available next

See API versions and Beta status for current API availability and the requirements for using a workflow in production.

Troubleshooting

I receive 401 Unauthorized when signing in

Check the email address and password sent to POST /frontoffice/auth/login. The API returns this response only for invalid credentials.

I receive 403 Forbidden while generating a key

Ask a company administrator to verify that your user has permission to generate API keys. Do not share another user's key as a workaround.

I lost an API-key secret

Revoke the affected key with PATCH https://api.uat.roots.finance/frontoffice/api-keys/{id}, then generate a new key. Update the secret in your deployment before revoking a key that is still in use.