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#

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:

Authorization: Bearer pt_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Creating API Keys#

Go to Org Settings → API Keys
Click New API Key
Enter a descriptive name (e.g. playwright-automation, ci-pipeline-staging)
Select the scopes the key needs
Click Create Key
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#

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#

To rotate a key:

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

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

Security Best Practices#

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 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#

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.