# Authentication

> API keys, OAuth access tokens, and mobile session tokens — when to use each and how to revoke them.

Every request carries a **Bearer** token in the `Authorization` header:

```http
GET /api/v1/me HTTP/1.1
Host: ornek.solk.app
Authorization: Bearer sk_9fQ…
```

If the token is missing, invalid, expired, or revoked, the response is `401 unauthorized`. Never send the token in the URL (query string).

## Token types

| Type | Prefix | Issued by | Lifetime | Permissions | When to use |
|---|---|---|---|---|---|
| **API key** | `sk_` | An admin, in **Settings → Developers** (*Ayarlar → Geliştiriciler*) | Until revoked | All permissions of the admin who created it | Server-to-server integrations, Zapier / Make / n8n, scripts |
| **OAuth access token** | `mcp_` | The OAuth flow, with the user's consent | 1 hour (refresh token: 60 days) | The consenting user + scope (`crm.read`, `crm.write`) | Apps that act on behalf of users, MCP clients |
| **Mobile session token** | `xk_` | [`POST /api/v1/login`](/rest-api/auth/login) | 90 days (installation setting) | The signed-in user | The Solk mobile app; your own mobile client |

## API key

1. Open **Settings → Developers** (*Ayarlar → Geliştiriciler*). Only admins can see this page.
2. Name the key and click **Create key** (*Anahtar oluştur*). The key is shown only once.
3. Store the key in an environment variable or a secrets vault.

The page shows each key's name, creation time, and last-used time; **Revoke** (*İptal et*) invalidates a key immediately. Because a key acts with the identity of the admin who created it, deactivating that admin also invalidates the key — for company-wide integrations, we recommend creating a dedicated "integration" admin user.

:::note
API keys and OAuth tokens don't prompt for two-step verification, but IP restrictions still apply. Changes made with a key are recorded in the audit log under the key owner's name.
:::

## OAuth

If your app runs under multiple users' own accounts (for example, a desktop add-in or a multi-tenant SaaS), get each user's permission through OAuth. The user sees your app and the requested scopes on a consent screen; as soon as they grant access, you receive an access token. Users can remove access at any time in **Settings → App connections** (*Ayarlar → Uygulama bağlantıları*).

| Scope | Grants |
|---|---|
| `crm.read` | Read companies, people, opportunities, actions, email threads, calendar, and dashboards |
| `crm.write` | Create companies, people, opportunities, tasks, notes, and activity logs; complete tasks; change stages |

Non-`GET` requests made without `crm.write` receive `403 insufficient_scope`. For the full flow, see [OAuth app](/rest-api/oauth).

## Mobile session

If you're building your own mobile client, [sign in](/rest-api/auth/login) with a username and password. For users with two-step verification enabled, the first request returns `401 otp_required`; ask the user for the 6-digit code and repeat the same request with the `otp` field. After 5 failed attempts from the same IP, sign-in is locked for 60 seconds (`429 locked`). On sign-out, [`POST /api/v1/logout`](/rest-api/auth/logout) revokes the token.

## Security recommendations

- Never put tokens in source code, in JavaScript that runs in the browser, or in public repositories.
- Create a separate key for each integration so that revoking one doesn't affect the others.
- Send requests only over `https://`; Solk installations redirect HTTP to HTTPS.
- If a token leaks, revoke it immediately. When a user is deactivated (or deprovisioned through SCIM), all of their tokens are revoked automatically.