Authentication
Ema's API uses a two-step authentication flow: first generate an API key, then exchange it for a short-lived access token (JWT). All subsequent API calls use the access token in the Authorization header.
Authentication Flow
1. GenerateApiKey (gRPC-Web) --> API Key (long-lived)
2. GenerateAccessToken (REST) --> Access Token (JWT, short-lived)
3. Use Access Token in Authorization header for all API callsStep 1: Generate an API Key
Create an API key for a user within a specific tenant. This is a gRPC-Web endpoint.
| Property | Value |
|---|---|
| URL | /auth.v1.AuthService/GenerateApiKey |
| HTTP Method | POST |
| Protocol | gRPC-Web over HTTP |
Headers
| Header | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer token with user authentication |
Content-Type | string | Yes | application/grpc-web+proto |
x-grpc-web | string | Yes | 1 |
Request
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address of the user to generate the key for |
scope | ApiKeyScope | No | The scope for the API key. Default: API_KEY_SCOPE_GLOBAL. |
Response
| Field | Type | Description |
|---|---|---|
api_key | string | The generated API key |
api_key_id | string | The generated API key ID |
Example
# Encode the request
cat <<EOF | protoc -I=. --encode=auth.v1.GenerateApiKeyRequest \
service/auth/v1/auth.proto > request.bin
email: "[email protected]"
EOF
# Frame the request
python3 -c 'import sys,struct; data=sys.stdin.buffer.read(); \
sys.stdout.buffer.write(b"\x00"+struct.pack(">I",len(data))+data)' \
< request.bin > framed_request.bin
# Send the request
curl -X POST https://your-instance.ema.co/auth.v1.AuthService/GenerateApiKey \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/grpc-web+proto" \
-H "x-grpc-web: 1" \
--data-binary @framed_request.bin \
--output response.binFirst-time setup: If you do not yet have an access token, see Access Token for Root Tenant API Key for instructions on obtaining one from your browser session.
For the full gRPC-Web encoding/decoding process, see Handling gRPC-Web Requests.
Step 2: Generate an Access Token
Exchange an API key for a JWT access token using the REST endpoint.
| Property | Value |
|---|---|
| URL | /api/auth/generate_access_token |
| HTTP Method | POST |
| Protocol | REST (HTTP) |
Headers
| Header | Type | Required | Description |
|---|---|---|---|
x-ema-api-key | string | Yes | Your API key |
Request Body
This endpoint does not require a request body. Pass the API key in the x-ema-api-key header.
Response Body
| Field | Type | Description |
|---|---|---|
access_token | string | JWT access token for API authorization |
Example
curl -X POST https://your-instance.ema.co/api/auth/generate_access_token \
-H "x-ema-api-key: your-api-key-here"Response:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}Token Expiration
| API Key Type | Token Lifetime |
|---|---|
| Global API key | 24 hours |
| Chatbot API key | 30 minutes |
When a token expires, generate a new one by calling GenerateAccessToken again with the same API key.
Using the Access Token
Include the access token in the Authorization header of every API request:
Authorization: Bearer <access_token>This applies to both REST and gRPC-Web endpoints.
API Key Types
Ema supports two types of API keys:
- Global API key: Full access to all Builder Platform APIs. Tokens last 24 hours.
- Chatbot API key: Restricted to chatbot-related endpoints. Tokens last 30 minutes.
Related
- Getting Started -- End-to-end quickstart
- Handling gRPC-Web Requests -- Detailed gRPC-Web encoding guide
- Access Token for Root Tenant API Key -- First-time token setup