API keys

Create, review and revoke your organization's API keys for the Direct API and the Partner API.

An API key lets another system use Morphic without anyone opening it: start your workflows over the Partner API, or generate and edit media over the Direct API. The 'API keys' tab is visible to admins only.

Go straight there: studio.morphic.com/settings/api-keys

The API keys page, with the base URL, the organization ID and the button to create a key

A key belongs to the organization

Not to the person who created it. It keeps working when they leave, every admin sees it listed and can revoke it, and every run it starts is billed to the organization.

Create a key

Open the tab

Open the organization dropdown (the Morphic logo, top-left), select Settings, then click 'API keys' in the left sidebar.

The settings sidebar with API keys selected, last in the organization's screens

Click New key

Give it a name you will recognize in a month: the system it lives in, not "key 2".

The form for a new API key: name, scopes, workflows, credit limits and expiry

Choose its scopes

Pick only what the key needs. The first three are for the Partner API, the rest for the Direct API, which appear once Morphic has turned the Direct API on for your organization.

  • workflows:read: read a workflow and the inputs it takes
  • runs:write: start runs, and register webhook endpoints
  • runs:read: read a run's status and its finished assets, and list webhook endpoints
  • projects:read: read projects and their files
  • assets:read: find and read assets
  • assets:write: upload assets and edit them
  • generations:write: generate images, video and audio, which spends credits

Then tick the box to agree to the Morphic Terms of Use, including the Developer API section.

Limit it to specific workflows

Optional, and worth doing. Tick 'Limit this key to specific workflows' and pick them. A run of anything else is refused, which contains the damage if the key leaks. Left unticked, the key can run every workflow the organization can.

Limit this key to specific workflows ticked in the new key form, with a search box and the organization's workflows to pick from

Set its credit limits

Set 'Total credits this key may ever spend', or choose 'No total limit (unlimited)'. Per-day and per-month caps are optional; leave one blank to leave that window uncapped.

A total is worth setting. Pick it from what the integration should be able to spend before someone looks at it again, not from what it will spend: it is a circuit breaker, not a budget. A window cap cannot be higher than the total, because the total would bind first.

Credits for a run started with the key are billed to the organization and counted against that key's limits. A run the key started keeps counting against it even if somebody later steps into the chat and takes over. Otherwise a colleague answering one question would move the rest of the run onto the organization's general pool. That person's own credit limit, if they have one, still applies too.

A day is a UTC day and a month a UTC calendar month. A charge that would take the key past any of its limits is refused, and the message names the key and the limit it hit.

Choose an expiry

Never, 30 days, 90 days or a year. An expired key stops authenticating on its own, which is the cheapest form of rotation.

Copy the secret

The secret is shown once. Morphic keeps only a hash of it, so it cannot be shown again. Copy it into your secret manager before closing the dialog.

Anyone holding the key can start runs that spend your organization's credits. Never commit it, never put it in a browser, never send it over email or chat. If one leaks, revoke it.

What the list shows

Each key shows its name, whether it is a live or test key, the leading characters of its secret (enough to match against your own records), its scopes, how many workflows it can run, its credit limits, and when it was last used. Expired and revoked keys stay listed so you can see what happened to them.

An organization may hold up to 10 keys that can authenticate at once. Expired and revoked keys do not count against that.

Change a key's credit limits

  1. Find the key in the list.
  2. Click the '…' menu beside it and select 'Edit limits'.
  3. Change the total, or a per-day or per-month cap, and save. Clear a cap to lift it.

The new limits apply from the key's next charge, including on runs it has already started. That makes this the fix when a run stops on the key's limit, and it works on a revoked key too: its runs still spend against it, so lowering its limits is how you stop them.

Revoke a key

  1. Find the key in the list.
  2. Click the '…' menu beside it and select 'Revoke key'.
  3. Confirm.

Calls using it start failing within seconds. Runs already in flight finish and are still billed. Revoking cannot be undone. To rotate a key, create the replacement first, move your traffic to it, then revoke the old one.

Where the spend shows up

Credits spent over the API are billed to the organization and attributed to the key that spent them. In Credit usage, API spend shows as one more member, 'API', and a charge from a named key as 'API · ' and the key's name.

  • In 'Overview', turn on 'Split API by key' to break the API's spend down per key.
  • A Partner API run started with a user_email that is not one of your members is listed under that email in 'Usage history', so you can see what each of your own users spent. A run whose user_email belongs to a member is that member's. See Start a workflow run.

If you have any trouble or have any questions, feel free to reach out. We're happy to help. Write to us at support@morphic.com.

On this page