Each request to /v1 needs a personal access token. Send it in the Authorization header.
Authorization: Bearer talyn_pat_...
Only GET /v1/openapi.json works without a token.
Only tokens that start with talyn_pat_ work on /v1. These tokens do not work:
- App sign-in tokens
- MCP tokens
- Session tokens
Each of these answers 401 with the code invalid_token.
- Open the Talyn app.
- Go to Settings, then API tokens.
- Choose a name, the access, and an expiry.
- Optionally, bind the token to one workspace.
- Copy the token.
The app shows the plaintext one time. Talyn stores only a SHA-256 hash of it. If you lose the token, create a new one.
- The default expiry is 90 days.
- The longest expiry is 365 days.
- You can also choose that the token never expires.
You can revoke a token in the same screen at any time.
There are 16 scopes.
| Scope | Gives access to |
|---|---|
workspaces:read |
GET /workspaces, GET /workspaces/{id} |
teams:read |
List your teams and roles. |
spaces:read |
List spaces and visible sessions in them. |
spaces:write |
Start sessions in spaces: POST /sessions with space_id. That request also needs sessions:write. Also includes spaces:read. |
repositories:read |
List and get repositories. Read repository settings, instructions, the Setup list, the workspace sandbox setup and the setup recipe. |
repositories:write |
Change repository settings. Write and delete repository instructions. Write the Setup list and the workspace sandbox setup. Accept, dismiss, retry and revert setup steps. Also includes repositories:read. |
sessions:read |
Read sessions, chats and events. Open the streams. Read changes, diffs, files, scripts, previews, queues, checkpoints, timing and workspace readiness. |
sessions:write |
Start, archive, restore and retry sessions. Open, change and close chats. Send messages. Stop turns. Run scripts. Make preview links. Open and merge pull requests. Ask the agent to fix checks, resolve conflicts or address reviews. Continue as a thread. Resize sessions. Start a session on a pull request. Also includes sessions:read. |
memory:read |
List and get workspace memory entries. |
memory:write |
Save, change, forget and restore memory entries. Also includes memory:read. |
pull_requests:read |
Read pull requests, their descriptions and the merge queue. |
pull_requests:write |
Refresh pull requests from GitHub. Turn auto-keep on or off. Add, remove and re-submit merge-queue entries. Also includes pull_requests:read. |
code_reviews:read |
Read code reviews, their findings and their history. |
code_reviews:write |
Start and stop code reviews. Dismiss findings and undo a dismissal. Post findings to GitHub. Also includes code_reviews:read. |
webhooks:read |
List and read webhook endpoints, their deliveries and the event types. |
webhooks:write |
Create, change, delete and test webhook endpoints. Rotate secrets. Redeliver. Also includes webhooks:read. |
The token form sets the access for each resource: None, Read, or Read & write. It shows these resources:
- Workspaces
- Teams and Spaces, only when the
spacesfeature is on for your account - Repositories
- Sessions
The form does not offer the pull_requests, code_reviews, webhooks or memory scopes yet. The API accepts these scopes, but you cannot create a token with them in the app.
The form has two presets:
| Preset | Scopes |
|---|---|
| Read only | workspaces:read, repositories:read, sessions:read. With spaces on, also teams:read and spaces:read. |
| Full access | workspaces:read, repositories:read, sessions:write. With spaces on, also teams:read and spaces:write. |
A write scope includes its read scope. A token with sessions:write can call all sessions:read endpoints.
GET /me needs any valid token. It needs no scope.
A request without the needed scope answers 403 with the code insufficient_scope. The error body has required_scope. The WWW-Authenticate header also names the scope.
{
"error": {
"type": "permission_error",
"code": "insufficient_scope",
"message": "This token does not have the \"sessions:write\" scope.",
"required_scope": "sessions:write",
"request_id": "req_01JBX8Z6Q4M8N3V5K7T2W9Y1C0"
}
}A token can be bound to some of your workspaces. GET /me shows the binding in token.workspace_ids. The value null means all workspaces.
- A workspace outside the binding answers
404workspace_not_found. The API does not say that the workspace exists. - If the token is bound to exactly one workspace, you can leave out
workspace_id. This applies toGET /repositories,GET /sessions,POST /sessions,GET /pull-requests,GET /merge-queue,GET /memoriesandPOST /memories. - If the token reaches more than one workspace,
workspace_idis required. A request without it answers400missing_parameter.
curl -s https://api.talyn.dev/v1/me \
-H "Authorization: Bearer $TALYN_TOKEN"const res = await fetch("https://api.talyn.dev/v1/me", {
headers: { Authorization: `Bearer ${process.env.TALYN_TOKEN}` },
});
if (!res.ok) throw new Error(`Token check failed: ${res.status}`);
const me = await res.json();
console.log(me.token.scopes, me.token.workspace_ids, me.token.expires_at);| Status | Code | Meaning |
|---|---|---|
| 401 | missing_token |
The request has no bearer token. |
| 401 | invalid_token |
The token is not a valid talyn_pat_ token. |
| 401 | token_revoked |
The owner revoked the token. |
| 401 | token_expired |
The token passed its expiry. |
| 403 | account_not_allowed |
The account may not use this deployment. |
| 403 | insufficient_scope |
The token lacks the needed scope. |
| 403 | public_api_unavailable |
The API is not on for the account. |
| 403 | workbenches_unavailable |
Sessions are not on for the account. |
| 403 | spaces_unavailable |
The spaces feature is not on for the account. Team and space endpoints need it. |
A 401 includes a WWW-Authenticate: Bearer realm="talyn-api" header. See errors for the full list.
- Treat the token like a password. It acts as you.
- Keep it in an environment variable or a secret store. Do not commit it.
- The API sends no CORS headers. A browser cannot read a
/v1answer. Do not use a token in a web page. Call the API from a server or a script. - Use the smallest scopes and the shortest expiry that your job needs.
- Revoke a token that leaks.
- A token never has admin rights.