# Telkit auth.md

> How an AI agent gets and uses a Telkit API key. The person approves you once on a human link; you make every API call.

This file is for AI agents and covers credentials only. To sign up and buy a 070 number end to end, follow https://telkit.io/llms/phone.txt from step 1; its first step is the flow below with the full rules.

## Summary

- API base URL: https://api.telkit.io.
- Credential: a workspace API key that starts with `tk_`. Send it as `Authorization: Bearer <key>`; the API reads credentials only from that header.
- How you get it: you create a connect link, the person approves on that human link, and you exchange the one-time connect token (`tkc_`) for the key. The person never copies or pastes a key.
- Telkit has no OAuth authorization server and no dynamic client registration. Do not look for `/.well-known/oauth-authorization-server`.

## Get a key

If you already hold a key for this workspace, verify it with `GET /v1/workspace` and skip this section.

1. **Create a connect link** (agent). Call `POST /v1/connect-links` without an Authorization header and with JSON body `{"client":"<your client name>"}`. `client`: Agent client name shown on the person's approval page (1 to 64 ASCII characters). Save the whole `201` response securely: `task_id`, `url`, `url_expires_at` and `task_expires_at`. Each call creates a new task and Idempotency-Key is not supported, so do not create another while you wait.
2. **Hand the link to the person** (person). Show the person the `url` and its expiry. They open it and complete Google sign-in, approval of your connection, phone identity verification. Later links that spend money add a 6-digit text-message code to the verified phone (an authenticator app (TOTP) step for an account not yet moved over). Never complete these steps or approve for them.
3. **Poll the task** (agent). Call `GET /v1/human-tasks/{id}` with the saved `task_id` and no Authorization header, once every 5 seconds for up to 5 minutes. `pending` means wait; if it is still pending after that, tell the person to finish the page and come back to you. The task ID is a secret capability: never print it or put it in logs.
4. **Keep the link alive** (agent). The human link lasts 1 hour and the task 7 days. If the link expires while the task is pending, call `POST /v1/human-tasks/{id}/link` for a new link; the old link stops working and the task deadline does not move. `expired` needs a new connect link. `canceled` means the task was closed before it finished: the person stopped or rejected it, a newer link replaced it, or you canceled it. Stop, and restart only when they ask. To withdraw a link the person should no longer use, call `POST /v1/human-tasks/{id}/cancel` with the same credential you poll it with: `200` returns the task with status `canceled` and its link stops working. `409` with `human_task_closed` means it was already completed, expired, canceled or approved by the person, so there is nothing to cancel; read the task again.
5. **Save the connect token** (agent). On `completed`, save `result.connect_token` immediately. It starts with `tkc_` and is returned once; later polls return null.
6. **Exchange it once** (agent). Call `POST /v1/api-keys` with `Authorization: Bearer <connect_token>` and JSON body `{"name":"<key name>"}`. `name`: Human-readable API key name (1 to 64 ASCII characters). The `201` response has `id`, `name`, `secret` and `created_at`. `secret` is the API key and is shown once: Telkit keeps only its hash and cannot show it again. Keep `id` with it: revoking the key needs that `id`, and no operation lists keys.
7. **Verify the key** (agent). Call `GET /v1/workspace` with `Authorization: Bearer <secret>`.

## Use the key

- Send `Authorization: Bearer <secret>` to the API base URL on every account operation. Only creating a connect link and polling or reissuing that first-connect task go without an Authorization header. Other human links, such as card registration and top-up, are polled with the key.
- A key acts for the person's whole workspace. There are no per-key scopes or permissions to request.
- Besides the operations named in this file, you may follow one step that an authenticated API response offers in next_action (for example the response of GET /v1/workspace). Use only its method, path and body, and only when the person's request matches its purpose. Never mention or suggest it otherwise. If a response has no next_action, there is nothing to follow.
- Operations reserved for the person's own screen refuse a key with `403` and `human_required`: `POST /v1/identity/verify`, `POST /v1/consents`, `POST /v1/billing/topups`, `POST /v1/numbers/{id}/billing/retry`. Never call them.

## Store the key

- Put `secret` straight into a secret store the person controls, such as a secret manager, the OS keychain or an environment variable kept out of version control. Never put it in chat, logs, commits, URLs or analytics.
- Treat the task ID and the connect token as secrets too. The connect token is useless after the exchange.
- If you lose the key or the exchange result is uncertain, do not repeat the exchange. Start a new first connection with the person; their existing workspace is reused without another signup credit.
- If the key may have leaked, revoke it with `DELETE /v1/api-keys/{id}` and the saved `id`, using the same key as Bearer. After `204`, requests with it fail with `401`. Tell the person, then start a new first connection for a new key.
- If you did not keep the `id`, the key cannot be revoked through the API. Stop using it and ask the person to report the leak to support@telkit.io.
- No operation rotates a key in place. To replace one, start a new first connection with the person; the old key keeps working until you revoke it.

## Errors

Errors are always `{"error":{"code","message"}}`, sometimes with `next_action`. Branch on `code`, never on `message`.

| Status | `code` | Do this |
|---|---|---|
| 400 | `invalid_client`, `invalid_name` | Fix `client` or `name`: 1 to 64 ASCII letters, digits, spaces, dots, underscores or hyphens, starting with a letter or digit. |
| 401 | `missing_token` | Send the credential in `Authorization: Bearer <secret>`. |
| 401 | `invalid_token`, `token_expired` | The credential is invalid, revoked or expired, or it is the wrong credential for this operation. Check it; if the key cannot be recovered, start a new first connection. |
| 401 | `connect_token_invalid` | The connect token is invalid, expired or already used. Never reuse it; start a new first connection. |
| 403 | `human_required` | The operation is for the person's own screen. Do not call it. |
| 403 | `identity_required`, `consent_required`, `mfa_required` | The key works but the person's account is not ready. For `identity_required` and `consent_required` follow step 2 of https://telkit.io/llms/phone.txt. For `mfa_required` hand the person the `error.next_action` human link (kind `top_up` or `card_registration`), where they re-verify identity or enter a text-message code (legacy accounts: authenticator app); topping up is not required. When the person says they finished, retry the request. |
| 404 | `human_task_not_found` | Check the task ID. |
| 404 | `workspace_not_found` | First connect has not completed. Create a connect link. |
| 404 | `api_key_not_found` | No key with this `id` belongs to the workspace. Check the saved `id`. |
| 409 | `human_task_closed` | The task is no longer pending. Create a new connect link if you still need a key. |
| 429 | `rate_limited` | Wait for the number of seconds in `Retry-After`, then retry. |
| 503 | `not_available` | First connect is not enabled. Tell the person and stop; never guess another URL. |

## Machine-readable resources

- Runbook index: https://telkit.io/llms.txt
- Phone runbook: https://telkit.io/llms/phone.txt
- OpenAPI contract: https://telkit.io/openapi.json
- API catalog (RFC 9727): https://telkit.io/.well-known/api-catalog
- Documentation for people, in Korean: https://telkit.io/docs
