seminara.online Authentication & API Keys Guide

This document specifies how autonomous AI agents and developer clients discover, register, claim, and authenticate with the Seminara API (https://seminara.online/api/v1).

1. Discover

Agents discover authentication capabilities and metadata via RFC 9728 Protected Resource Metadata (PRM) and RFC 8414 Authorization Server (AS) metadata:

• Protected Resource Metadata: https://seminara.online/.well-known/oauth-protected-resource
• Authorization Server Metadata: https://seminara.online/.well-known/oauth-authorization-server
• Agent Auth Manifest Anchor: The AS metadata advertises the agent_auth block pointing to this specification.

When calling any protected API endpoint without valid credentials, the server returns an HTTP 401 response carrying the WWW-Authenticate header:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://seminara.online/.well-known/oauth-protected-resource"

2. Pick a Method

Seminara supports three authentication methods for agents:

1. Static API Key (Self-Serve): Long-lived token generated in the Seminara Dashboard (https://seminara.online/dashboard/settings).
2. Anonymous Agent Registration (anonymous): Instant token provisioning via register_uri for ephemeral testing.
3. Identity Assertion (identity_assertion): Cryptographically verified agent identity supporting verified_email or JSON Web Signature (urn:ietf:params:oauth:token-type:id-jag).

3. Register

Autonomous agents can dynamically obtain credentials by calling the register_uri:

POST https://seminara.online/api/v1/auth/register
Content-Type: application/json

{
  "client_name": "Autonomous Sales Agent",
  "identity_type": "anonymous"
}

Response:

{
  "status": "registered",
  "token_type": "Bearer",
  "access_token": "ag_live_example12345",
  "expires_in": 86400,
  "scope": "sessions:read sessions:write analytics:read",
  "claim_uri": "https://seminara.online/api/v1/auth/claim",
  "revocation_uri": "https://seminara.online/api/v1/auth/revoke"
}

4. Claim

When an anonymous agent needs to link its session to a registered Seminara account or organization, it invokes the claim_uri. Claiming binds the ephemeral token to an authenticated human user or organization account, unlocking elevated permissions such as leads:read and checkout:write:

POST https://seminara.online/api/v1/auth/claim
Content-Type: application/json
Authorization: Bearer ag_live_example12345

{
  "claim_id": "usr_claim_abc123"
}

Response:

{
  "status": "claimed",
  "claim_id": "usr_claim_abc123",
  "verified": true,
  "bound_at": "2026-08-23T04:00:00.000Z"
}

5. Use the Credential

Include the bearer token in the Authorization header of all subsequent API and MCP calls:

GET /api/v1/agent/sessions HTTP/1.1
Host: seminara.online
Authorization: Bearer ag_live_example12345

6. Errors

Standard authentication errors follow RFC 6749 and RFC 9457:

• 401 Unauthorized: Missing or invalid token. Includes WWW-Authenticate: Bearer resource_metadata="https://seminara.online/.well-known/oauth-protected-resource".
• 403 Forbidden: Insufficient scopes. Check scopes_supported in RFC 9728 metadata.
• 429 Too Many Requests: Rate limit exceeded.

7. Revocation

To revoke an active credential or terminate an agent session, call the revocation_uri:

POST https://seminara.online/api/v1/auth/revoke
Content-Type: application/json

{
  "token": "ag_live_example12345"
}

Response:

{
  "status": "revoked",
  "token_revoked": true,
  "revoked_at": "2026-08-23T04:05:00.000Z"
}