Authentication

Overview

The Lucaro API uses Bearer token authentication. You can generate API tokens from your account settings, or use OAuth 2.0 for user-based authentication in your applications.

API Tokens

API tokens are the simplest way to authenticate with the Lucaro API. They are ideal for server-to-server integrations and scripts.

Generating a Token

1. Navigate to Settings > API Tokens in your Lucaro dashboard
2. Click Generate New Token
3. Give your token a descriptive name (e.g., "Production Server")
4. Select the appropriate scopes for your use case
5. Copy and securely store the generated token

Using the Token

Include your API token in the Authorization header of all API requests:

curl -X GET "https://api.lucaro.dev/v2/projects" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Token Scopes

API tokens can be scoped to limit their access:

OAuth 2.0

Use OAuth 2.0 when building applications that need to access Lucaro on behalf of users. We support the Authorization Code flow with PKCE.

Register Your Application

1. Go to Settings > OAuth Applications
2. Click Create Application
3. Enter your application name and redirect URIs
4. Save your Client ID and Client Secret

Authorization Flow

1. Redirect users to the authorization endpoint:

https://auth.lucaro.dev/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=read:projects read:dashboards&
  state=RANDOM_STATE&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256

2. Exchange the authorization code for tokens:

curl -X POST "https://auth.lucaro.dev/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "code_verifier=CODE_VERIFIER"

Token Refresh

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token:

curl -X POST "https://auth.lucaro.dev/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Error Responses

Authentication errors return standard HTTP status codes: