Authentication

All Livepin endpoints require authentication using an API key and a JWT bearer token. You first obtain a JWT by logging in with your API key and secret, then include both the API key and the JWT in every subsequent request.

Use this endpoint to exchange your API key and secret for a JWT token.

API key login

POST

/api/user/login-with-api-key

curl --location 'http://localhost:1337/api/user/login-with-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "api_key": "<YOUR_API_KEY>",
    "api_secret": "<YOUR_API_SECRET>",
    "expiry": 3600
  }'

Request body

Parameter	Type	Required	Description
`api_key`	string	Yes	Your API key.
`api_secret`	string	Yes	Your API secret.
`expiry`	number	No	JWT expiration time in seconds. Defaults to the server-configured value.

Response body

Field	Type	Description
`jwt`	string	The JWT bearer token for authenticated requests.
`user.id`	number	Your user ID.
`user.username`	string	Your username.
`user.email`	string	Your email address.
`user.phone_number`	string	Your phone number.
`user.account_type`	string	Your account type (e.g., `ADMIN`).

Making authenticated requests

After obtaining a JWT, include the following headers in every subsequent API request:

x-api-key: <YOUR_API_KEY>
Authorization: Bearer <JWT_TOKEN>

Example: authenticated request

curl --location 'http://localhost:1337/api/contacts' \
  --header 'x-api-key: <YOUR_API_KEY>' \
  --header 'Authorization: Bearer <JWT_TOKEN>'

Manage API keys

API keys can also be created and revoked programmatically. These calls use the same x-api-key + Authorization: Bearer headers.

Name
GET /api/api-accesses
Description
List your API keys.
Name
GET /api/api-accesses/:id
Description
Get one API key.
Name
POST /api/api-accesses
Description
Create a new API key.
Name
PUT /api/api-accesses/:id
Description
Update an API key.
Name
DELETE /api/api-accesses/:id
Description
Revoke an API key.

List API keys

curl "$LIVEPIN_API_BASE_URL/api/api-accesses" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Create API key

curl -X POST "$LIVEPIN_API_BASE_URL/api/api-accesses" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"production-server"}'

Revoke API key

curl -X DELETE "$LIVEPIN_API_BASE_URL/api/api-accesses/:id" \
  -H "x-api-key: $LIVEPIN_API_KEY" \
  -H "Authorization: Bearer $JWT_TOKEN"

Security recommendations

Rotate your API key and secret periodically.
Keep your API key, API secret, and JWT in secret managers — never in source code.
Use separate credentials per environment (dev / stage / prod).
Revoke and regenerate tokens immediately if compromised.
Set a reasonable expiry value to limit the lifetime of each JWT.

Back to quickstart