Authentication

Code reaches yggy with one of three credentials. Each acts as a member or as the organization, and yggy checks the same members, projects and permissions as in the app.

Method	Acts as	Use it for
Personal key	You, with your project access	Scripts, notebooks, local tools
Organization key	The organization, with exactly the permissions it was given	Pipelines and services the whole organization relies on
MCP sign-in	The member who signs in	AI clients such as Claude Code, Cursor and VS Code

Personal keys

Create one under Developers → API keys, in Your personal keys. A personal key acts as you, with your project access, and stops working when you leave the organization.

Organization keys

Organization owners and admins create organization keys under Developers → API keys, in Organization keys. An organization key acts as the organization, not as the person who created it:

• It has exactly the permissions it was given. You can only give it permissions your own role has; asking for more is refused with 400 and the code API_KEY_PERMISSION_EXCEEDS_ROLE.
• It keeps working when its creator leaves the organization or changes role. Revoke keys you no longer need.
• It reaches every project shared with the organization, or only its project if you limit it to one. In an organization with more than 100 shared projects, limit it to one project; otherwise its calls answer 409 with the code ORG_KEY_TOO_MANY_PROJECTS. It can’t open private documents. Facts extracted from documents follow the visibility of the knowledge graph, which is per project, so facts from a private document in a project the key reaches can be readable.
• It can’t use a person’s own data, such as chats, notifications, personal connections, cases or notes. Those calls answer 403 with the code ORG_KEY_PERSONAL_SCOPE; use a personal key for them.
• It can’t import from personal connections today. Import through an organization connection, or use a personal key.

Use it for services and pipelines.

A new key starts with read permission on every area (shown as Read all in the key list) and the expiry Never. Narrow both when you create it:

1. Name it after the client that uses it, for example Quarterly reporting export.
2. Under Permissions, keep only the permissions the client needs.
3. Under Expiry, choose 30, 60 or 90 days or 1 year. Choose Never only if the client cannot rotate keys.
4. Copy the key and store it in a secret manager. The key value appears once.

API tokens and audit log explains how to rotate or revoke a key and where its audit events are.

Send the key

Send the key in the x-api-key header or as Authorization: Bearer <key>. Name the organization in x-yggy-organization-id, by id or by slug. The samples read the key from the YGGY_API_KEY environment variable, so it stays out of your scripts. This lists the first 20 completed documents:

curl --fail-with-body \
  --header "x-api-key: $YGGY_API_KEY" \
  --header "x-yggy-organization-id: acme-corp" \
  "https://api.yggy.tech/api/v1/documents?status=completed&limit=20"

A successful response has this form:

{
  "documents": [
    {
      "documentId": "0x123",
      "title": "Q4 report.pdf",
      "content": "",
      "contentType": "application/pdf",
      "status": "COMPLETED",
      "createdAt": "2026-08-01T09:30:00.000Z",
      "updatedAt": "2026-08-01T09:32:14.000Z",
      "tripleCount": 84
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

The response can contain more fields. Send one credential per request: a key next to a different credential, such as a browser session cookie, is refused with 400 and AMBIGUOUS_PRINCIPAL. The same key in both headers is accepted.

MCP sign-in

MCP clients such as Claude Code, Cursor and VS Code do not use keys. The first connection opens yggy in a browser, where the member signs in, picks the organization and approves the scopes. The client then acts as that member. How MCP works lists the scopes and explains how to revoke a client.

A token from an MCP sign-in works on the MCP server only. The REST API answers it with 401; use an API key there.

OAuth apps

Owners and admins can register an application that signs members in to yggy.

1. Open Developers → Apps.
2. Choose Create app.
3. Enter a name and one or more redirect URIs, one per line. Use https. http is accepted only for localhost.
4. Copy the client ID and the secret. The secret is shown once. New secret replaces it; the previous secret stops working immediately.

The application sends the member to the authorize URL and exchanges the code at the token URL. Both are shown when you create the app. For https://api.yggy.tech they are:

https://api.yggy.tech/api/v1/auth/oauth2/authorize
https://api.yggy.tech/api/v1/auth/oauth2/token

The member signs in and approves access. Request graph:read. You can also request graph:write, graph:review, documents:read, documents:write, docs:read, and offline_access. Send the client secret in the token request body (client_secret_post), with the same redirect URI and the PKCE code verifier:

curl --fail-with-body --request POST "https://api.yggy.tech/api/v1/auth/oauth2/token" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=<code>" \
  --data-urlencode "redirect_uri=https://app.example.com/callback" \
  --data-urlencode "client_id=<client id>" \
  --data-urlencode "client_secret=$YGGY_OAUTH_CLIENT_SECRET" \
  --data-urlencode "code_verifier=<verifier>"

A successful response includes access_token. With offline_access, it also includes refresh_token. Deleting the app in Developers → Apps ends that application’s access.

Permissions

A call needs the permission its operation requires. A key without it gets 403, and the message names the missing permission. A personal key never does more than your role allows. An organization key has exactly its own permissions, which can’t exceed the role of the admin who created it. An organization key without any permission gets 403 with the code API_KEY_NO_PERMISSIONS.

Area	Permissions	Covers
Documents	documents:create , documents:read , documents:update , documents:delete , documents:share	Access to upload, view, and manage documents
Projects	project:create , project:share , project:update , project:delete , project:read	Access to create and manage projects
Knowledge Graph	graph:create , graph:share , graph:update , graph:delete , graph:read , graph:review	Access to query and modify the knowledge graph
Chat	chat:read , chat:write	Access to chat sessions and AI queries
API Keys	apiKey:create , apiKey:read , apiKey:delete	Access to create and manage API keys
Billing & Subscription	billing:read , billing:update	Access to view and manage billing information
Organization Settings	organization:create , organization:update , organization:delete , organization:read	Access to update organization details and settings
Members	member:create , member:update , member:delete , member:read	Access to invite and manage organization members
Invitations	invitation:create , invitation:cancel , invitation:update , invitation:delete , invitation:read	Access to send and manage member invitations
Roles & Permissions	ac:create , ac:update , ac:delete , ac:read	Access to create and manage custom roles
Providers	providers:create , providers:read , providers:update , providers:delete	Access to connect and manage external data source providers
Connections	connections:read , connections:manage	Access to view and revoke authorized AI-assistant/MCP-client connections
Audit Log	auditLog:read	Access to view organization audit logs
Workflows	workflow:read , workflow:cancel	Access to view workflow status and invocations
Investigations	investigations:create , investigations:read	Access to create and view project investigations

Actions that need a signed-in person

Some actions refuse every API key with 403 and the code API_KEY_NOT_ALLOWED, because only the person signed in to the yggy app may take them:

• create API keys;
• read Usage and logs and manage Webhooks under Developers;
• delete your account or the organization, and purge the organization’s data;
• change the IP allowlist or the log export destination;
• delete an entity from the graph;
• dictate text; in yggy notes, delete all notes and open note images.

The Reference lists only the operations a key can call.

IP allowlist

On Pro and Enterprise, owners and admins can limit API keys and MCP clients to known networks under Security → API Access. While the allowlist is on, a call from any other address gets 403 with the code FORBIDDEN, and the attempt is recorded in the audit log. The yggy app in a browser is not affected.

Next

• Upload a file and extract it with your key.
• Look up any operation in the Reference.