Authentication

Universal API supports multiple authentication methods. This guide explains how to authenticate your requests and manage your API credentials.

Authentication Overview

Universal API supports several authentication methods. The server checks them in this priority order:

Priority	Method	Format	Use Case
1	User Token (Recommended)	`Authorization: Bearer uapi_ut_xxx`	Programmatic API access (all your keys injected)
2	Role Token	`Authorization: Bearer uapi_rt_xxx`	Scoped access with attached key set
3	Resource Key	`Authorization: Bearer uapi_rk_xxx`	Deprecated — use role tokens instead
4	Cognito JWT	`Authorization: Bearer eyJ...`	Browser sessions (automatic)
5	Legacy Headers	`X-Uni-SecretUniversalKey`	Deprecated — use Bearer tokens instead
6	Anonymous	No auth	Public resources only, rate-limited

All authenticated methods provide the same benefits:

Access to private resources you own
Higher rate limits (authenticated users get 60 requests per minute vs 10 requests per day for anonymous users)
Your API keys for third-party services are automatically made available to actions
Access to your request history and logs

Browser Sessions

If you're using the Universal API web dashboard, authentication is handled automatically. Your browser session uses a Cognito JWT token — no manual token setup needed.

Method 1: Bearer Token (Recommended)

Bearer tokens are the recommended authentication method. They are simpler to use (single header), work across all endpoints including the streaming API, and can be scoped and revoked independently.

Creating an Access Token

Go to your Universal API dashboard
Navigate to the Access Tokens section
Click Create Token and give it a descriptive name
Copy the token — it will start with uapi_ut_

WARNING

Store your access token securely! It cannot be viewed again after creation. If lost, revoke it and create a new one.

Using Bearer Tokens

Add the Authorization header to your requests:

bash

# curl example
curl -X GET "https://api.universalapi.co/user/credits" \
  -H "Authorization: Bearer uapi_ut_your_token_here"

javascript

// JavaScript fetch
const response = await fetch('https://api.universalapi.co/agent/list', {
  headers: {
    'Authorization': 'Bearer uapi_ut_your_token_here'
  }
});

python

# Python requests
import requests

response = requests.get(
    'https://api.universalapi.co/agent/list',
    headers={
        'Authorization': 'Bearer uapi_ut_your_token_here'
    }
)

Streaming with Bearer Token

Bearer tokens work with the dedicated streaming API Gateway at stream.api.universalapi.co:

bash

curl -N "https://stream.api.universalapi.co/agent/{agentId}/chat" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer uapi_ut_your_token_here" \
  -d '{"prompt": "Hello!"}'

Managing Access Tokens

Operation	Endpoint	Method
List tokens	`/access-tokens`	GET
Create token	`/access-tokens`	POST
Revoke token	`/access-tokens/{tokenId}`	DELETE

You can create multiple tokens for different applications and revoke them independently without affecting your other integrations.

Role Tokens

Role tokens (uapi_rt_*) carry their own embedded set of API keys. Unlike user tokens (which inject all your global keys), a role token only injects the specific keys you attach to it. This enables two powerful use cases:

Use Case 1: Scoped Key Access

Instead of exposing all your third-party keys to every API call, create a role token with only the keys needed for a specific task:

bash

# Create a role token with only AWS keys
curl -X POST "https://api.universalapi.co/user/token/create" \
  -H "Authorization: Bearer uapi_ut_your_user_token" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenName": "aws-only",
    "tokenType": "role",
    "keys": {
      "aws_access_key_id": "AKIA...",
      "aws_secret_access_key": "wJal...",
      "aws_region": "us-east-1"
    }
  }'
# Returns: { "token": "uapi_rt_abc123...", "keyCount": 3, "keyNames": ["aws_access_key_id", ...] }

Now use the role token — only the embedded AWS keys are available at runtime:

bash

curl "https://api.universalapi.co/mcp/{serverId}" \
  -H "Authorization: Bearer uapi_rt_abc123..."
# Runtime context.keys = { aws_access_key_id, aws_secret_access_key, aws_region }
# Your OpenAI, Stripe, and other global keys are NOT exposed

Use Case 2: Author Key Injection

Resource authors can attach a role token to their MCP server, action, or agent. At runtime, the author's keys are injected alongside the invoking user's keys — enabling authors to use their own paid service credentials (e.g., AWS Textract, OpenAI) and recover costs via author pricing.

bash

# 1. Author creates a role token with their service credentials
curl -X POST "https://api.universalapi.co/user/token/create" \
  -H "Authorization: Bearer uapi_ut_author_token" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenName": "textract-credentials",
    "tokenType": "role",
    "keys": {
      "aws_access_key_id": "AKIA-author...",
      "aws_secret_access_key": "wJal-author..."
    }
  }'

# 2. Author attaches the role token to their resource
curl -X PUT "https://api.universalapi.co/mcp-server/update" \
  -H "Authorization: Bearer uapi_ut_author_token" \
  -H "Content-Type: application/json" \
  -d '{
    "serverId": "mcp-xxx",
    "authorRoleToken": "uapi_rt_textract_token"
  }'

# 3. When any user invokes this MCP server, the author's keys
#    are available as context.authorKeys at runtime

Key Priority

When both author keys and invoking user keys exist, the invoking user's keys take priority on conflicts. Author keys fill in any keys the user doesn't have.

Managing Role Tokens

Role tokens support the same operations as user tokens:

Operation	Endpoint	Method
Create role token	`/user/token/create`	POST (with `tokenType: "role"`)
List tokens	`/user/token/list`	GET (filter with `?type=role`)
Get token details	`/user/token/{tokenId}`	GET (returns key names, never values)
Update keys	`/user/token/update`	PUT (with `keys` field)
Revoke	`/user/token/revoke`	DELETE
Regenerate	`/user/token/{tokenId}/regenerate`	POST

Security

Role token key values are never returned in any API response — only key names are visible. If you need to change a key value, update the role token with the new value.

Method 2: Legacy Headers

The legacy method uses two custom headers. This still works across all endpoints but requires managing two credentials.

Finding Your Credentials

You can find your User ID and Secret Universal Key in your Universal API dashboard under the "API Credentials" section.

WARNING

Keep your Secret Universal Key secure! Do not share it publicly or commit it to version control systems.

Using Legacy Headers

javascript

// JavaScript fetch
const response = await fetch('https://api.universalapi.co/action/act-ac6a4e471bea45dc?prompt=Hello', {
  headers: {
    'X-Uni-UserId': 'your-user-id',
    'X-Uni-SecretUniversalKey': 'your-secret-key'
  }
});

python

# Python requests
import requests

response = requests.get(
    'https://api.universalapi.co/action/act-ac6a4e471bea45dc',
    params={'prompt': 'Hello'},
    headers={
        'X-Uni-UserId': 'your-user-id',
        'X-Uni-SecretUniversalKey': 'your-secret-key'
    }
)

Using Query Parameters

You can also append legacy credentials to the URL as query parameters:

https://api.universalapi.co/action/act-ac6a4e471bea45dc?prompt=Hello&userId=your-user-id&secretUniversalKey=your-secret-key

WARNING

This method exposes your credentials in URLs, which may be logged by servers or appear in browser history. Use with caution.

In the Request Body (POST requests)

For POST requests, you can include legacy credentials in the JSON body:

json

{
  "prompt": "Hello",
  "userId": "your-user-id",
  "secretUniversalKey": "your-secret-key"
}

Testing Your Authentication

To confirm your authentication is working correctly:

With Bearer Token:

bash

curl -X GET "https://api.universalapi.co/user/credits" \
  -H "Authorization: Bearer uapi_ut_your_token_here"

With Legacy Headers:

bash

curl -X GET "https://api.universalapi.co/user/credits" \
  -H "X-Uni-UserId: your-user-id" \
  -H "X-Uni-SecretUniversalKey: your-secret-key"

If properly authenticated, you'll see your credit balance. If not authenticated, you'll get an authorization error.

Testing with ModHeader in Chrome

ModHeader is a Chrome extension that lets you easily add custom headers to your browser requests:

Install ModHeader: Get it from the Chrome Web Store
Configure Headers (choose one method):
- Bearer Token: Add header Authorization with value Bearer uapi_ut_your_token_here
- Legacy: Add X-Uni-UserId and X-Uni-SecretUniversalKey headers
Test Authentication:
- With ModHeader enabled, visit: https://api.universalapi.co/action/list
- You should see all actions, including private ones you own

Best Practices

Use Bearer Tokens for new integrations — they're simpler and more secure.
Use Environment Variables: Store credentials in environment variables rather than hardcoding them.
Create separate tokens for different applications so you can revoke them independently.
Implement Rate Limiting: Be aware of the rate limits and implement appropriate backoff strategies.
Rotate credentials periodically for enhanced security.

Next Steps

Now that you understand how to authenticate with Universal API, you can:

Learn about API key management for third-party services
Set up OAuth connections for services like Google
Try streaming agent chat with real-time responses
Explore the API Reference

Authentication ​

Authentication Overview ​

Method 1: Bearer Token (Recommended) ​

Creating an Access Token ​

Using Bearer Tokens ​

Streaming with Bearer Token ​

Managing Access Tokens ​

Role Tokens ​

Use Case 1: Scoped Key Access ​

Use Case 2: Author Key Injection ​

Managing Role Tokens ​

Method 2: Legacy Headers ​

Finding Your Credentials ​

Using Legacy Headers ​

Using Query Parameters ​

In the Request Body (POST requests) ​

Testing Your Authentication ​

Testing with ModHeader in Chrome ​

Best Practices ​

Next Steps ​

Authentication

Authentication Overview

Method 1: Bearer Token (Recommended)

Creating an Access Token

Using Bearer Tokens

Streaming with Bearer Token

Managing Access Tokens

Role Tokens

Use Case 1: Scoped Key Access

Use Case 2: Author Key Injection

Managing Role Tokens

Method 2: Legacy Headers

Finding Your Credentials

Using Legacy Headers

Using Query Parameters

In the Request Body (POST requests)

Testing Your Authentication

Testing with ModHeader in Chrome

Best Practices

Next Steps