Creating an Access Key

This guide explains how to programmatically create or update users and retrieve their access keys using Liona’s API. This is ideal for automating user provisioning in your applications or backend systems.

Note

To use this API, you need an API key with administrative privileges. Learn how to generate an API key first.

Understanding Access Keys

Access keys allow your users to authenticate with AI providers through Liona. Unlike API keys, which have administrative privileges, access keys have limited access based on the policies you assign.

When creating users programmatically:

You define user details like ID and policy
The API returns an access key for the user
You can distribute this access key to the user or store it in your system

API Endpoint

⚠️

Warning

This endpoint should only be called from your backend services. Never call this endpoint from client-side code or expose your API key in client applications.

Field	Value
URL	`https://liona.ai/v1/admin/make-access-key`
Method	POST
Authentication	API Key (in Authorization header)

Request Parameters

Parameter	Type	Required	Description
`user_id`	string	Yes	A unique identifier for the user
`policy_id`	string	Yes (for new users)	The ID of the policy to associate with this user
`email`	string	No	User’s email address for identification (optional)
`expire_seconds`	integer	No	Access key expiration in seconds (defaults to 1 week if not specified or if a value greater than 1 week is provided)

Response Structure

The API returns a JSON object containing:

Field	Type	Description
`access_key`	string	The access key for the user
`expires_at`	string	ISO 8601 timestamp when the access key expires

Examples

cURL


curl -X POST https://liona.ai/v1/admin/make-access-key \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "user_id": "user123",
    "email": "[email protected]",
    "policy_id": "pol_12345",
    "expire_seconds": 86400
  }'

JavaScript


// Using fetch
async function createOrUpdateUser() {
  try {
    const response = await fetch('https://liona.ai/v1/admin/make-access-key', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
      },
      body: JSON.stringify({
        user_id: 'user123',           // Required: Unique identifier for the user
        email: '[email protected]',    // Optional: User's email
        policy_id: 'pol_12345',       // Required for new users: Policy to apply
        expire_seconds: 86400         // Optional: Access key expiration in seconds (default: 1 week)
      })
    });
 
    if (!response.ok) {
      throw new Error(`Error: ${response.status}`);
    }
 
    const data = await response.json();
    console.log('Access key:', data.access_key);
    console.log('Access key expires at:', data.expires_at);
 
    return data;
  } catch (error) {
    console.error('Failed to create/update user:', error);
  }
}

Python


import requests
 
def create_or_update_user():
    url = "https://liona.ai/v1/admin/make-access-key"
    headers = {
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY"
    }
    payload = {
        "user_id": "user123",          # Required: Unique identifier for the user
        "email": "[email protected]",   # Optional: User's email
        "policy_id": "pol_12345",      # Required for new users: Policy to apply
        "expire_seconds": 86400        # Optional: Access key expiration in seconds (default: 1 week)
    }
 
    try:
        response = requests.post(url, json=payload, headers=headers)
        response.raise_for_status()  # Raise exception for 4XX/5XX status codes
 
        data = response.json()
        print(f"Access key: {data['access_key']}")
        print(f"Access key expires at: {data['expires_at']}")
 
        return data
    except requests.exceptions.RequestException as e:
        print(f"Failed to create/update user: {e}")
        return None

How It Works

This endpoint performs the following operations:

If the user with the specified user_id doesn’t exist in the project:
- Creates a new user with the provided details
- Associates the user with your project
If the user already exists:
- Updates the user’s policy and/or email if provided in the request
For the access key:
- If the user has an existing valid API-generated access key, extends its expiration
- Otherwise, generates a new access key
Returns the access key and its expiration date

Error Handling

The API may return the following errors:

Status Code	Description
400	Bad Request - Missing required fields or validation error
401	Unauthorized - Invalid or missing API key
500	Internal Server Error - Various internal failures such as policy not found or access key generation failure

Limitations

Access key expiration is capped at 1 week (604,800 seconds) for security reasons
If you specify an expiration longer than 1 week, it will be automatically adjusted to 1 week
If you don’t specify an expiration, the access key will expire after 1 week by default

Next Steps

Now that you can programmatically create users and access keys, you might want to:

Connect to an SDK using this access key.