# Octomatica API authentication

Octomatica's public Agent-as-a-Service API currently uses scoped bearer API keys. This document describes the published key workflow. It does not claim OAuth support for the `/v1` API.

## Discover

- API base URL: `https://dash.octomatica.ru/v1`
- OpenAPI specification: `https://octomatica.ru/openapi.json`
- Interactive documentation: `https://dash.octomatica.ru/v1/docs`
- Authentication scheme: `Authorization: Bearer octo_live_...`

## Pick a method

Use a dashboard-created API key for server-to-server access. Keep it on your backend. Do not expose it in browser code, mobile packages, prompts, logs, or client-visible configuration.

## Register

A human account owner signs in to `https://dash.octomatica.ru`, opens Integrations, API Keys, and creates a key. No unauthenticated or dynamic client registration endpoint is currently published.

## Claim and scope

Choose the narrowest space access:

1. Only spaces this key creates. Recommended for integrations.
2. One specific space.
3. All account spaces. Use only when account-wide access is required.

Set a daily USD cap appropriate for the integration. The plaintext key is shown once. Store it in a secret manager.

## Use the credential

```http
Authorization: Bearer octo_live_REDACTED
Content-Type: application/json
```

Every API request requires the bearer header. A missing, malformed, unknown, or revoked key returns HTTP 401 with the JSON error code `INVALID_KEY`.

## Errors

- `401 INVALID_KEY`: key missing, malformed, unknown, or revoked.
- `403 KEY_NOT_BOUND_TO_SPACE`: the key cannot access the requested space.
- `404 SPACE_NOT_FOUND`: the space does not exist or is not visible to this key.
- `429 QUOTA_EXCEEDED`: the key's daily cap or the end user's cumulative cap is reached.

Errors follow `{ "error": { "code", "message", "details", "trace_id" } }`. Preserve `trace_id` when contacting support.

## Revocation and rotation

Revoke compromised or unused keys in Dashboard, Integrations, API Keys. Create a replacement, update the backend secret, verify it with a read request, and then revoke the old key. Never send a real key to support or place it in an agent prompt.

For account or integration help, contact labs@octomatica.ru.