# auth.md

This file tells an agent how to get a Cadenya credential for its user. Cadenya is a hosted agent runtime, and its API lives at `https://api.cadenya.com`.

There are two paths. If the user has a Cadenya account, they log in. If they don't, the agent can create a temporary workspace for them, with no signup, and the user claims it later.

**Cadenya does not implement the auth.md OAuth registration endpoints yet.** There's no `/.well-known/oauth-protected-resource`, no `/agent/identity`, and no identity assertion exchange. Everything below uses Cadenya's own endpoints, which are listed exactly.

## Pick a path

- **The user has an account.** Run `cadenya auth login`, or ask them for an API key from the API keys page at `app.cadenya.com/account/apiKeys`. Don't create a temporary workspace for someone with an account: they can't claim it.
- **The user has no account.** Create a temporary workspace (below). It's a real workspace with an API key that reaches only that workspace.

With the CLI installed, `cadenya auth status` says which credential is in use.

## Create a temporary workspace

With the CLI (`brew install cadenya/tools/cadenya` or `choco install cadenya`):

```sh
cadenya workspaces create --temporary
```

Or over HTTP. The request is unauthenticated, and one carrying credentials is rejected:

```http
POST https://new.cadenya.com/v1/temporary_workspaces
Content-Type: application/json

{ "name": "My project", "expireAfter": "86400s", "source": "TEMPORARY_WORKSPACE_SOURCE_API" }
```

Every field is optional. `expireAfter` is between `3600s` and `86400s`, and defaults to 24 hours.

```json
{
  "workspaceId": "workspace_01HXKD2E5NQM3T9AYWCF133E3Q",
  "accountId": "account_01HXKD2E5NQM3T9AYWCFTJHJVF",
  "apiKey": "...",
  "claimUrl": "https://app.cadenya.com/claim#...",
  "claimToken": "...",
  "expiresAt": "2026-11-09T19:49:13Z",
  "nextStep": "..."
}
```

This response is the only copy of the API key and the claim token. The CLI stores both in `.cadenya/temporary.json` and adds that file to `.gitignore`.

## Use the credential

Send the API key as a bearer token:

```http
GET https://api.cadenya.com/v1/workspaces/{workspaceId}/agents
Authorization: Bearer <apiKey>
```

Before the claim, the workspace runs on the Unclaimed plan: lower limits, no promotional model credit, and a free scripted demo model. Some features return `REQUIRES_CLAIM` until the user claims. For real model output before the claim, the user can add their own provider key.

## The claim

**The claim URL is a secret.** Whoever opens it and signs in becomes the owner. Show it to the user only in a private reply, and never write it to a file, a commit, a PR, an issue, or a log.

The user claims in one of two ways:

- Open `claimUrl` and sign in or sign up. The token sits in the URL fragment, which browsers never send to a server.
- Run `cadenya auth login` in the project directory. It claims the workspace and logs the user in, in one step.

Only someone without a Cadenya account can claim. A claim adds $5 in promotional model credit, removes the expiry, and **revokes the temporary API key**. The next request with that key fails with `TEMPORARY_WORKSPACE_CLAIMED`. Get a new credential with `cadenya auth login`, or from the API keys page.

Check the claim at any time with the temporary key:

```http
GET https://api.cadenya.com/v1/workspaces/{workspaceId}/temporary
Authorization: Bearer <apiKey>
```

`state` is `STATE_UNCLAIMED`, `STATE_PENDING`, `STATE_CLAIMED`, or `STATE_EXPIRED`. The CLI's `cadenya workspaces claim-status --wait` blocks until it's claimed or expired.

## Expiry

An unclaimed workspace is permanently deleted at `expiresAt`, along with everything in it. It can't be recovered. Tell the user the deadline in their local time.

## Errors

| Error | Where | What to do |
| --- | --- | --- |
| 429 `RATE_LIMITED`, with `retry-after` | `new.cadenya.com` | Wait the `retry-after` seconds. Don't retry in a loop. |
| 429 `TEMPORARY_WORKSPACE_LIMIT_REACHED` | `new.cadenya.com` | This network already holds the most live temporary workspaces it may. Reuse one, or wait for one to be claimed or expire. |
| 503 `DISABLED` or `PROVISIONING_DISABLED` | `new.cadenya.com` | Creation is switched off. Point the user at [sign-up](https://app.cadenya.com/signup). |
| 429 `RESOURCE_EXHAUSTED`, with `retry-after` | `api.cadenya.com` | Too many requests. Wait the `retry-after` seconds. |
| `REQUIRES_CLAIM` | `api.cadenya.com` | The feature needs a claimed workspace. Tell the user, and keep working on the rest. |
| `ACCOUNT_PROVISIONING` | `api.cadenya.com` | The workspace is still being set up. Retry after the delay in the error. |
| `TEMPORARY_WORKSPACE_CLAIMED` | `api.cadenya.com` | The key was revoked by a claim. Get a new credential. |
| `TEMPORARY_WORKSPACE_EXPIRED` | `api.cadenya.com` | The workspace was deleted. Create a new one only if the user wants it. |

## More

- The full agent guide: [cadenya-start-without-account skill](https://cadenya.com/.well-known/agent-skills/cadenya-start-without-account/SKILL.md)
- Setup steps for coding agents: [cadenya.com/agents.md](https://cadenya.com/agents.md)
- Docs: [cadenya.com/docs](https://cadenya.com/docs)