AimRack API

Authentication

A client inherits exactly the identity it authenticates as — and can only do what that identity can. There are two flows, by client type.

Connector (OAuth)

Claude.ai, Claude Desktop, and ChatGPT authorize over OAuth — add the server URL and approve the connection in your browser. There's no key to manage. The connection inherits the role and company of whoever authorized it.

API key

Claude Code, Cursor, VS Code, Codex, and any headless or CI client send a scoped key as a bearer token: Authorization: Bearer <api-key>. Create one in ; the key carries its own scopes. stdio-only clients bridge through mcp-remote. There is no login step and no token to refresh: every request carries the key.

Creating a key

Choose New API Key, give it a Name, optionally set Expires At (blank means it never expires), check the actions it may take in the permission grid, and save. AimRack shows the full key once, in a dialog headed "You can only see this key once. Store it safely.", beside a ready-to-paste command that connects Claude Code to AimRack with it. Only a SHA-256 hash of the key is kept, so a lost key cannot be shown again: delete it and create a new one.

Permissions

A connector inherits your role and company. A key does not inherit the permissions of the person who created it: it acts with exactly the module actions checked on it, and only within its company, so a key with none checked authenticates but can read and write nothing. The key is read on every request, so tightening its scopes or deleting it takes effect on the next call. Use a separate key per client, so revoking one doesn't break the rest.

Rate limit

Every key allows 60 requests per minute, counted per key, so one integration spending its allowance never slows another. The limit is set by the platform: the key list shows it, and the form has no field for it. A request over the limit is refused with 429 and the headers Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; wait the seconds Retry-After names before sending again.

Errors

Status

When it happens

401

Connector: re-authorize from your client. Key: it's missing, malformed, expired, or deleted — recreate it and update the Authorization header.

403

The identity lacks the required module permission.

429

The key sent more than 60 requests in a minute. Wait for Retry-After, then send again.

Keys and webhooks

A key lets you call AimRack; a webhook lets AimRack call you when a record you subscribed to changes. The two are independent, and a webhook is not signed with a key. The usual pattern uses both: the webhook says that a record changed, and your key fetches the record as it is now.