# Authentication

All Lathe Studio API requests are authenticated using API keys. Keys are tied to your organization and carry specific scopes that control what the key can do.

---

## [API Key Format](/content/docs/api/authentication#api-key-format/index.html)

Keys follow this format:

```
pt_live_<hex string>
```

Example:

```
pt_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

Include the key as a Bearer token in the `Authorization` header on every request:

```http
Authorization: Bearer pt_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

---

## [Creating API Keys](/content/docs/api/authentication#creating-api-keys/index.html)

1. Go to **Org Settings → API Keys**  
2. Click **New API Key**  
3. Enter a descriptive name (e.g. `playwright-automation`, `ci-pipeline-staging`)  
4. Select the scopes the key needs  
5. Click **Create Key**  
6. **Copy the key immediately** — it is shown only once

Keys are stored as hashed values. Lathe Studio cannot retrieve the plaintext key after creation.

---

## [Scopes](/content/docs/api/authentication#scopes/index.html)

Scopes are selected at creation time and cannot be changed. Create a new key if you need different scopes.

| Scope               | Description                                     |
|---------------------|-------------------------------------------------|
| `builds:read`      | Read build records                              |
| `builds:create`    | Create builds via POST /builds                  |
| `builds:update`    | Update build metadata                           |
| `testruns:read`    | Read test run records and results               |
| `testruns:create`  | Create test runs                               |
| `results:read`     | Read execution results                           |
| `results:submit`   | Submit automation results via POST /testruns/{id}/results |
| `projects:read`    | List projects and test cases                    |
| `webhooks:manage`  | Manage webhook subscriptions                     |

**Principle of least privilege**: Create separate keys per use case. A CI pipeline that only creates builds needs `builds:create` — not `projects:read` or `results:submit`.

---

## [Key Rotation](/content/docs/api/authentication#key-rotation/index.html)

To rotate a key:

1. Create a new key with the same scopes  
2. Update your CI/CD secrets with the new key  
3. Verify requests succeed with the new key  
4. Delete the old key from **Org Settings → API Keys**

There is no automated rotation — key rotation is a manual process.

---

## [Security Best Practices](/content/docs/api/authentication#security-best-practices/index.html)

- **Never commit keys to source control.** Use your CI/CD platform's secrets store (GitHub Actions Secrets, GitLab CI Variables, AWS Secrets Manager, etc.)
- **Use environment-specific keys.** Have separate keys for staging and production pipelines.
- **Audit key usage.** The API Keys table in Org Settings shows each key's last used timestamp.
- **Delete unused keys.** Remove keys for deprecated pipelines or departed team members immediately.

---

## [OAuth 2.0 (Enterprise)](/content/docs/api/authentication#oauth-20-enterprise/index.html)

OAuth 2.0 authorization code flow is planned for Enterprise tier. This enables third-party integrations that act on behalf of a specific user rather than the organization. Contact support for early access.

---

## [Troubleshooting](/content/docs/api/authentication#troubleshooting/index.html)

**401 Unauthorized** — The key is missing, malformed, or has been deleted. Check the `Authorization` header format: `Bearer pt_live_...` (note the space after `Bearer`).

**403 Forbidden** — The key exists but lacks the scope needed for this endpoint. Check which scopes were assigned when the key was created.