# SIMOSphere AI — Authentication Guide > How to authenticate with the SIMOSphere AI API. This document covers API key authentication (current) and OAuth 2.0 (planned), and is intended for both human developers and autonomous agent_auth consumers. --- ## Discover SIMOSphere AI exposes standard discovery endpoints so that clients — whether human-operated tools or autonomous agents — can locate the correct authentication mechanism without hard-coding URLs. - **API Base URL:** `https://api.simosphereai.com` - **OpenAPI Specification:** `https://api.simosphereai.com/openapi.json` - **Agent Discovery:** `https://simosphereai.com/.well-known/agent.json` - **OAuth Authorization Server Metadata (RFC 8414):** `https://api.simosphereai.com/.well-known/oauth-authorization-server` - **OAuth Protected Resource Metadata (RFC 9728):** `https://api.simosphereai.com/.well-known/oauth-protected-resource` An agent that receives a `401 Unauthorized` response with a `WWW-Authenticate: Bearer` header should follow the `authorization_servers` link in the protected-resource document to obtain the correct token endpoint and supported grant types. The `agent_auth` block in the authorization-server metadata describes the available identity_assertion types and credential workflows for machine clients. --- ## Pick a method Currently one method is available for production use. OAuth 2.0 with PKCE is planned for Q4 2026 to support third-party application integrations and user-delegated access patterns. | Method | Status | Use Case | |-----------------|---------|---------------------------------------------| | API Key (Bearer)| Live | Server-to-server, CLI tools, AI agents | | OAuth 2.0 + PKCE| Planned | Third-party apps, user-delegated access | For autonomous agents, the recommended credential type is `api_key`. The `register_uri` for self-service account creation is published in the authorization-server metadata, so agents can programmatically direct users to the registration page without prior configuration. --- ## Register Create an account at the SIMOSphere AI onboarding portal to obtain access credentials. Registration is self-serve and does not require manual approval from an administrator. **Registration URI (register_uri):** ``` https://app.simosphereai.com/register ``` Registration requires the following information: - **Email address** — verified via a one-time magic link sent to the provided address - **Organisation name** — the tenant under which API keys and usage will be scoped - **Plan selection** — all plans include a 14-day free trial with no credit card required Supported registration methods: - Email and password (minimum 12 characters, checked against common breach lists) - WebAuthn / Passkey (FIDO2) for passwordless authentication After completing registration, you will have access to the SIMOSphere AI Dashboard at `https://app.simosphereai.com`, where you can create API keys, manage team members, and monitor usage. --- ## Claim After registration, create an API key through the Dashboard or the Admin API. Each key is scoped to a single tenant and can be restricted to specific capabilities. ### Via Dashboard (recommended) 1. Log in at `https://app.simosphereai.com` 2. Navigate to **Settings > API Keys** 3. Click **Create New Key** 4. Choose scopes: `chat`, `embeddings`, `files`, `models` 5. Copy the key — it is shown only once and cannot be retrieved later ### Via Admin API ```bash curl -X POST https://api.simosphereai.com/admin/api-keys \ -H "Authorization: Bearer YOUR_JWT_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "My Agent Key", "scopes": ["chat", "embeddings"] }' ``` The response contains the full API key in the `key` field. Store it securely — it will not be returned again. Keys follow the format `sk_live_` for production and `sk_test_` for sandbox environments. Each key is 48 characters long, encoded in Base62 (a-z, A-Z, 0-9). For agent_auth flows, the credential issued is of type `api_key`. The identity_assertion model supports both `anonymous` (no prior identity required) and `identity_assertion` (where a pre-existing identity token such as `urn:ietf:params:oauth:token-type:id-jag` is exchanged for platform credentials). --- ## Use the credential Include the API key as a Bearer token in the `Authorization` header of every request. All API endpoints under `/v1/*` require this header. The gateway validates the key, checks rate limits, verifies plan entitlements, and routes the request to the appropriate LLM backend. ### Chat Completions Example ```bash curl -X POST https://api.simosphereai.com/v1/chat/completions \ -H "Authorization: Bearer sk_live_abc123..." \ -H "Content-Type: application/json" \ -d '{ "model": "mistral-small-latest", "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is the EU AI Act?"} ], "temperature": 0.7, "max_tokens": 1024 }' ``` ### Response Format Responses follow the OpenAI-compatible chat completions format. The `usage` object reports `prompt_tokens`, `completion_tokens`, and `total_tokens` for billing transparency. ```json { "id": "chatcmpl-abc123", "object": "chat.completion", "model": "mistral-small-latest", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The EU AI Act is..." }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 42, "completion_tokens": 128, "total_tokens": 170 } } ``` The `WWW-Authenticate` header is returned on `401` responses to indicate the expected authentication scheme: ``` WWW-Authenticate: Bearer realm="api.simosphereai.com", error="invalid_token" ``` --- ## Errors All error responses use a consistent JSON envelope with `type`, `message`, and `code` fields. Agents should implement retry logic for `429` responses and credential refresh logic for persistent `401` errors. | HTTP Status | Error Code | Meaning | Remediation | |-------------|------------------------|------------------------------------------|-----------------------------------------------------------| | 401 | `invalid_api_key` | Missing, malformed, or revoked API key | Verify the `Authorization: Bearer` header is correct | | 401 | `expired_token` | JWT token has expired (admin routes) | Re-authenticate via `/admin/auth/login` | | 403 | `insufficient_scope` | Key lacks required scope for this action | Add the missing scope in Dashboard > API Keys | | 403 | `plan_limit_exceeded` | Current plan does not include this feature | Upgrade the plan at `https://app.simosphereai.com/billing` | | 429 | `rate_limit_exceeded` | Too many requests in the current window | Wait for the number of seconds in the `Retry-After` header | ### Error Response Format ```json { "error": { "type": "authentication_error", "message": "Invalid API key provided. Check that your key is correct and has not been revoked.", "code": "invalid_api_key" } } ``` ### Rate Limits Rate limits are tied to the plan tier and are applied per API key. The following headers are included in every response: | Header | Description | |-------------------------|---------------------------------------------------| | `X-RateLimit-Limit` | Maximum requests allowed in the current window | | `X-RateLimit-Remaining` | Requests remaining in the current window | | `X-RateLimit-Reset` | Unix timestamp when the window resets | | `Retry-After` | Seconds to wait (only on 429 responses) | --- ## Revocation API keys can be revoked immediately. Once revoked, all in-flight and future requests using the key will fail with a `401 Unauthorized` response. Revocation is irreversible — to restore access, create a new key. ### Via Dashboard Navigate to **Settings > API Keys**, locate the target key, and click **Revoke**. The key becomes invalid within seconds. ### Via Admin API ```bash curl -X DELETE https://api.simosphereai.com/admin/api-keys/key_abc123 \ -H "Authorization: Bearer YOUR_JWT_TOKEN" ``` ### Key Rotation Best Practice To rotate keys without downtime, follow this sequence: 1. Create a new key with the same scopes as the existing key 2. Update your application configuration to use the new key 3. Verify that requests succeed with the new key 4. Revoke the old key This ensures zero downtime during rotation. We recommend rotating keys at least every 90 days, and immediately if a key may have been exposed. --- ## Key Properties | Property | Value | |---------------|------------------------------------------------| | Prefix | `sk_live_` (production) or `sk_test_` (sandbox) | | Length | 48 characters | | Encoding | Base62 (a-z, A-Z, 0-9) | | Scopes | `chat`, `embeddings`, `files`, `models`, `admin` | | Expiration | None by default (revoke manually) | | Rate limits | Tied to plan tier | ## Security Best Practices - Store keys in environment variables or a secrets manager — never commit them to source control - Use the narrowest scope possible for each key to limit blast radius - Rotate keys regularly (create new, verify, then revoke old) - Monitor usage in the Dashboard audit trail for anomalous patterns - Use `sk_test_` keys for development and CI/CD pipelines - Enable MFA on your SIMOSphere AI account for additional protection --- ## Programmatic Key Provisioning (Anonymous) For autonomous agents that need to claim credentials with only an email address, SIMOSphere AI will expose an agent registration endpoint: ```http POST https://api.simosphereai.com/agent/auth Content-Type: application/json { "identity_type": "anonymous", "email": "agent@example.com" } ``` **Response (201 Created):** ```json { "api_key": "sk_live_...", "expires_at": "2027-01-01T00:00:00Z", "scopes": ["chat", "embeddings", "models"] } ``` > **Note:** This endpoint is planned for Q4 2026. Until then, register at > [https://app.simosphereai.com/register](https://app.simosphereai.com/register) > and generate keys in the Dashboard under **Settings > API Keys**. The > `anonymous` identity type issues a free-tier key with standard rate > limits; upgrade to a paid plan for higher throughput. --- ## Links - Dashboard: https://app.simosphereai.com - Register: https://app.simosphereai.com/register - Developer Hub: https://simosphereai.com/developers - OpenAPI Spec: https://api.simosphereai.com/openapi.json - Auth Skill (this document): https://simosphereai.com/auth.md - MCP Server (Smithery): https://smithery.ai/servers/simosphereai/simosphere-ai - MCP Server (mcp.so): https://mcp.so/explore?q=simosphere - Support: info@simo-online.com