Authentication

Every call to the COP Gateway API carries a bearer token — your API key. Keys are created and managed in the dashboard at app.unnma.ai/keys.

Key shape

Every key starts with the prefix unnma-sk-, followed by a string of random characters. Example:

unnma-sk-abc123def456ghi789jkl012mno345pqr678stu901

We display the first eight characters (e.g. unnma-sk-abc1) in the dashboard for identification. The full value is shown exactly once — at the moment you create the key. After that, only you have it. We do not store the plaintext key; we store a SHA-256 hash. If you lose a key, you cannot recover it — you create a new one.

Sending the key

Pass the key as a bearer token in the Authorization header:

Authorization: Bearer unnma-sk-...

If you're using a vendor SDK, the SDK handles this header for you when you pass the key into its api_key / apiKey parameter — see the Quickstart examples.

Creating a key

In the dashboard:

1. Go to Keys.
2. Click Create key.
3. Give it a name (this is for your own bookkeeping — it appears nowhere on requests).
4. Optionally set a per-minute rate limit and a daily spend cap for this specific key.
5. Click Create. Copy the full key value before closing the dialog.

The defaults at creation are:

• Rate limit: 100 requests per minute.
• Daily spend cap: none (unlimited).

Both are user-configurable per key. See Rate limits for what these mean.

Revoking a key

In the dashboard, find the key in the Keys table and click Revoke. The key stops working immediately — within seconds, as our auth cache flushes. Revocation is a one-way state change; a revoked key cannot be re-activated. You create a new one.

Revoked keys remain visible in the dashboard for your audit history; they are not deleted from your account. Hard deletion happens only on account deletion.

Multiple keys

You can have multiple active keys at the same time. Common patterns:

• One key per environment (dev, staging, production).
• One key per service or worker.
• One key with a tight spend cap for experiments, one key without a cap for production traffic.

Rate limits and daily spend caps are per-key. There's also an account-level rate limit and an optional account-level daily spend cap that apply across all your keys combined. See Rate limits.

Security

Treat your API key like a password.

• Never commit it. Use environment variables, a secrets manager, or your platform's configuration system.
• Don't ship it to a browser. Anything visible in client-side code is visible to anyone who opens DevTools. If you need to make calls from a browser, proxy them through your own server.
• Rotate periodically. Create a new key, deploy it, then revoke the old one. There is no downtime if you stagger the swap.
• Use per-environment keys. A leaked dev key is contained when it's clearly scoped. A leaked production key isn't.
• Set a daily spend cap on each key. A cap of, say, $50/day is the difference between a small accident and a large one.

If you believe a key has been compromised, revoke it immediately and create a new one. Revocation is instant.

What happens when a key fails

If a request arrives with no key, an invalid key, or a revoked key, the gateway returns:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
 
{
  "error": {
    "type": "unauthorized",
    "message": "Invalid or missing API key.",
    "request_id": "req_01abc..."
  }
}

Full error envelope details: Error codes.