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

Terminal

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

JSON

{
  "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.

Warning

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.

Terminal

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

Response 200 OK

JSON

{
  "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.

Terminal

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

← PreviousHow It Works Next →Environments