Skip to main content
Every request to /api/v1 carries an API key as a bearer token. This page covers creating a key, choosing its scopes, the plan gate, and the errors you get when something is missing.

​
Send the key

Pass the key in the Authorization header on every request:
Keys look like yk_live_ followed by 43 characters. The SDKs read the key from YUNGLE_API_KEY (Python) or take it as apiKey (JavaScript). The CLI reads YUNGLE_API_KEY before anything else.

​
Create a key

Create keys in Settings → API keys. Give each key a name you will recognize later, such as ci-release or crm-sync, and pick its scopes.
  • The key is shown once. Yungle stores only a hash of it, so it cannot show it again. If you lose a key, revoke it and create another.
  • A key belongs to your own workspace and acts as its owner: its uploads count against that workspace’s storage and its plan decides what it can do. A member of someone else’s workspace cannot create a key for it.
  • A key does not expire. It works until you revoke it.
  • Revoking is immediate. The key is checked on every request, so the next request with it fails.

​
Scopes

A scope grants access to one kind of resource. Pick the narrowest set that does the job. Two rules apply to every scope:
  • A :write scope includes :read of the same resource. Every write returns what it changed, so a separate read scope would not hold anyway. transfers:write alone is enough to send a transfer and read its receipt.
  • Scopes never cross resources. transfers:write cannot read contacts.
A few endpoints describe the credential or a link rather than a resource, and accept a key with any scope: GET /me, GET /me/referral, POST /links/resolve and GET /imports/{fileId}. A key with no scopes is refused everywhere. There is no scope for billing, plan changes, workspace members, API keys or account deletion. Those stay in the dashboard. See What the API cannot do.

​
Free and paid plans

Every account can use the API. What the free plan reaches: The plan is checked live on every request. If a subscription lapses, the paid endpoints answer 402 from the next request and work again once it is renewed. Nothing needs re-issuing. A free workspace cannot create a key with collections:write; the dashboard refuses it at creation.

​
Authentication errors

Errors lists every error code.

​
Keep keys safe

  • Store keys in environment variables or a secrets manager, never in a repository.
  • Use one key per integration, so you can revoke one without breaking the others.
  • Do not ship a key to a browser or a mobile app. A key acts as your whole workspace, and the API is server-to-server.
  • If a key leaks, revoke it first and investigate second.

​
AI assistants use OAuth instead

When you connect Claude, ChatGPT, Cursor or another assistant to https://yungle.co/mcp, you sign in through your browser and approve what the assistant may do. No API key is involved, and emailing recipients is a separate permission you grant on the consent screen. See MCP.

​
Next steps

Quickstart

Use your key to send a first transfer.

Limits

Rate limits, email budgets and size ceilings.

Errors

Every error code and how to handle it.

MCP

Connect an AI assistant with OAuth.