Authentication

Lira uses two authentication methods — a JWT Bearer token for managing resources and an API key for calling verification endpoints.

Overview

Method	Header	Used for
JWT Bearer token	`Authorization: Bearer <token>`	Managing API keys, webhooks, and other dashboard resources
API Key	`X-API-Key: <key>`	Calling verification endpoints from your application

Use a Bearer token when your code is performing management operations: creating or revoking API keys, registering webhooks, or listing resources. Use an API key for every verification call your application makes.

Getting a Bearer token

curl -X POST https://api.lira.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@yourcompany.com",
    "password": "your-password"
  }'

Response 200 OK

{
  "accessToken": "eyJhbGci...",
  "refreshToken": "eyJhbGci...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Field	Description
`accessToken`	Short-lived JWT. Use this in `Authorization: Bearer` on management requests.
`refreshToken`	Long-lived token. Use this to obtain a new access token when the current one expires.
`expiresIn`	Number of seconds until the access token expires (e.g. `3600` = 1 hour).
`tokenType`	Always `Bearer`.

The accessToken is short-lived. Use the expiresIn value to schedule a refresh before it expires. When a request returns 401 with "token expired", call the refresh endpoint (below) to get a new access token silently.

Important: Store your refresh token securely — in a secrets manager, secure cookie, or encrypted storage. If it is compromised, an attacker can generate new access tokens until the token is revoked.

Refreshing an access token

When your access token expires, use the refresh token to obtain a new one without requiring the user to log in again.

curl -X POST https://api.lira.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGci..."
  }'

Response 200 OK

{
  "accessToken": "eyJhbGci...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

When to refresh: when a management request returns 401 with the message "token expired", call this endpoint and retry the original request with the new accessToken.

Note: The refresh endpoint does not return a new refresh token. The original refresh token remains valid until it expires or is revoked by logging out.

Logging out

Invalidate the current refresh token. Any access tokens issued from it will also be rejected by Lira's servers after invalidation.

curl -X POST https://api.lira.com/api/v1/auth/logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGci..."
  }'

Response 204 No Content

After logging out, delete the stored refresh token from your application. To regain access, log in again using POST /auth/login.

Roles and permissions

Each user in your organization is assigned a role. Roles control which management operations are permitted.

Action	ORG_ADMIN	DEVELOPER	MEMBER
Create API keys	Yes	No	No
List API keys	Yes	Yes	No
Revoke API keys	Yes	No	No
Create webhooks	Yes	Yes	No
List and view webhooks	Yes	Yes	No
Update webhooks	Yes	Yes	No
Delete webhooks	Yes	No	No

Note: Verification endpoints (POST /verify/account, POST /verify/phone) use API keys, not Bearer tokens, and are not subject to role restrictions.

Error handling

Error	Status	Cause	Action
Invalid credentials	`401`	Wrong email or password on login	Check credentials and try again
Token expired	`401`	Access token has passed its `expiresIn` window	Call `POST /auth/refresh` to get a new access token
Forbidden	`403`	Your role does not permit this action	Use an account with a higher-privilege role
Invalid refresh token	`401`	Refresh token has been revoked or has expired	Log in again using `POST /auth/login`
Missing Authorization header	`401`	No `Authorization: Bearer` header on a management request	Add the header with a valid access token

Next steps

API Keys — create, list, and revoke API keys using your Bearer token
Environments — understand sandbox vs live and which key to use
Quickstart — end-to-end walkthrough from login to first verification

How It Works

Environments