Skip to content
Scalpels home

Scalpels is officially launching on October 31, 2026. Special early adopter pricing is available now.

← All documentation

Documentation

Slate

API credentials

Updated

Every request to /api/v1 needs a bearer credential:

Authorization: Bearer slate_…

Slate tokens start with slate_. A missing, malformed, unknown, revoked or wrong-purpose credential gets 401. Slate does not tell a caller which of these it was.

Purpose: slate.sources

A credential carries a purpose, the one thing it is allowed to do. Slate defines exactly one purpose, slate.sources, and it opens all five API endpoints: registering and reading sources, submitting runs, reading run status and fetching results. No other purpose opens the API, and there are no finer-grained scopes.

The installation reference

An installation credential is bound to a name, its subject reference. Slate accepts it only when that name matches this installation's reference exactly, character for character.

You do not have to configure it. The reference is the host in the deployment's APP_URL — for an application at https://slate.acme.com it is slate.acme.com. Every install has one, so installation credentials work on a fresh install with nothing set.

  • The reference identifies this installation of Slate. It is not a secret and grants nothing on its own.
  • Changing the host changes the reference, and that invalidates every credential issued against the old one. Callers start getting 401 straight away. Issue new credentials against the new reference.
  • A database restored into a second environment does not bring working credentials with it: that environment's APP_URL is different, so its reference is different and the restored credentials are refused.

Set SLATE_INSTALLATION_SUBJECT_REF only if you want a name that is not the host — for example to keep credentials working across a planned domain change. Edit the environment's variables in Laravel Cloud and redeploy. See Configuration.

Issue a credential

  1. Sign in to Slate (see Getting started) and open Settings → Installation credentials (/settings/credentials/installation).
  2. In the slate.sources / bearer form, choose the installation subject type.
  3. Enter the subject reference. It must be exactly this installation's reference: the host in your APP_URL, or your SLATE_INSTALLATION_SUBJECT_REF value if you set one.
  4. Give the credential a name that says who will use it, such as storefront production, and select Issue.

The token is shown once, on that page, and cannot be recovered afterwards. Copy it straight into your application's secret store. If you lose it, issue another one.

Anyone who can sign in to Slate can manage installation credentials, whatever their role.

Rotate and revoke

The list under Installation credentials shows each credential's name, kind, purpose, subject and status. Each has two actions:

  • Rotate issues a replacement token and shows it once. Update the caller with the new token.
  • Revoke stops the credential working immediately.

What a credential can see

Sources and runs belong to the subject that created them. A caller can read and use only its own:

  • A recipe can reference only sources created with the same subject. Another subject's source ID is treated exactly like an ID that does not exist.
  • Reading a run or source that belongs to someone else returns the same 404 as an unknown ID.

Two credentials issued against the same installation reference share one subject, so they see the same sources and runs. Agents calling Slate through Scalpels use a different subject per person. See MCP tools.

Webhook secrets are separate

The secret Slate uses to sign webhooks is not an API credential. It is created per run and shown once, in the response to the run submission. See Runs and results.