Authentication

OpenHuman API supports two authentication methods: API key and OAuth 2.0.

API Key

Obtaining an API Key

1. Log in to OpenHuman Console
2. Go to Settings → API Keys
3. Click Create New Key
4. Copy the key and store it securely

Using an API Key

curl -H "Authorization: Bearer sk_xxx" \
     -H "Content-Type: application/json" \
     https://api.tinyhumans.ai/v1/agents

const client = new OpenHuman({
  apiKey: 'sk_xxx',
});

Key Security

• Do not commit API keys to code repositories
• Use environment variables to store keys
• Rotate keys regularly
• Use key prefix sk_ to identify type

OAuth 2.0

Authorization Flow

User → Application → OpenHuman → User Authorization → Get Token → API Call

Step 1: Register Application

1. Go to Developer Console
2. Create a new application
3. Obtain client_id and client_secret

Step 2: Get Authorization Code

https://auth.tinyhumans.ai/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=read write

Step 3: Exchange Access Token

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

Response:

{
  "access_token": "at_xxx",
  "refresh_token": "rt_xxx",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Step 4: Use Access Token

curl -H "Authorization: Bearer at_xxx" \
     https://api.tinyhumans.ai/v1/agents

Refresh Token

After the access token expires, use the refresh token to obtain a new access token:

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

Scopes

Scope	Description
read	Read resources
write	Create and modify resources
delete	Delete resources
admin	Admin functions

Best Practices

1. Prefer API Keys - More convenient for simple scenarios
2. Use OAuth for user授权 scenarios - Such as connecting third-party services
3. Always Use HTTPS - Never transmit keys over HTTP
4. Principle of Least Privilege - Only request necessary scopes

Next Steps

• API Overview - API base information
• Endpoints - All API endpoints