Authentication
Create a Direct API key in Studio, choose its scopes and credit limits, and send it with every request.
Every request carries an organization API key as a bearer token.
Authorization: Bearer mor_live_9f2c…A key belongs to the organization, not to the person who created it. Every admin of the organization can see and revoke it, and it keeps working when its creator leaves the team. It stops working when it is revoked, when it expires, when the creator's account is suspended, or when Morphic switches the Direct API off for the organization.
Create a key
The Direct API scopes appear only once Morphic has enabled the Direct API for your organization. See Getting access.
- In Morphic Studio, open the organization dropdown (the Morphic logo, top left) and select Settings.
- In the left sidebar, click API keys. Only admins see this tab.
- Click New key.
- Enter a Name, choose the Scopes the key needs and, if it should not last forever, when it Expires.
- Under Credit limits, set the total the key may ever spend, and optionally a daily and a monthly limit.
- Tick I agree to the Morphic Terms of Use, including the Developer API section. This accepts the Terms of Use for the organization.
- Click Create key, then copy the secret into your secret manager. It is shown once.
Anyone holding the secret can spend your organization's credits up to the key's limits. Never put a key in a browser, a mobile app or a public repository.
Key format
mor_live_<64 hex characters>The prefix tells you, and secret scanners, which deployment the key is for.
Scopes
A key reaches only the tools its scopes allow. Choose the narrowest set.
| Scope | Label in Studio | Grants |
|---|---|---|
projects:read | Read projects and their files | list projects, workflows and Compose timelines |
assets:read | Find and read assets | list the library, read generations and their status, characters |
assets:write | Upload assets and edit them | pass media by URL, create Compose timelines |
generations:write | Generate images, video and audio (spends credits) | every tool that starts, edits or analyses media |
A call to a tool outside the key's scopes answers 403 insufficient_scope and names the missing scope in data.required_scopes. Endpoints and tools that need no scope, such as list_voices and /me, are open to every key. The tool catalog lists the scope each tool needs.
Credit limits
Every key carries spend caps, set when it is created. An admin can change them later with Edit limits.
| Limit | Required | Window |
|---|---|---|
total_credit_limit | yes | the lifetime of the key |
monthly_credit_limit | no | calendar month, UTC |
daily_credit_limit | no | calendar day, UTC |
- A paid call that would take the key past any limit is refused with
402 api_key_credit_limit_reachedbefore anything starts;data.periodsays which limit. - The organization's own balance applies on top: a call it cannot pay for is refused with
402 insufficient_credits. GET /v1/direct/mereturns the key's limits and current spend. See Credits and usage.
Rotate a key
- Create the new key.
- Deploy it.
- Revoke the old key with Revoke key.
An organization may hold up to 10 active keys, so rotation never needs a gap.
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.