API tokens and audit log

Create a separate API token for each client. Give it only the permissions and lifetime that the client needs.

Create a token

1. Open Developers → API keys.
2. Under Your personal keys or Organization keys, choose Create key.
3. Enter a name, such as Quarterly reporting export.
4. Select the expiry: 30, 60 or 90 days, 1 year, or Never.
5. Under Permissions, keep only the permissions the client needs.
6. Choose Create token.
7. Copy the token and store it in a secret manager.

The token value appears once. A new token starts with read permission on every area and the expiry Never; narrow both. Choose Never only if the client cannot rotate credentials.

Organization keys need an owner or admin. An organization key acts as the organization, not as the person who created it: it has exactly the permissions you give it, keeps working when that person leaves, and can’t use a person’s chats, notes, notifications, personal connections or private documents. Facts extracted from documents follow the knowledge graph’s visibility, which is per project. You can only give it permissions your own role has. Give it only the permissions and lifetime that the client needs.

Use either supported request header. x-yggy-organization-id accepts the organization id or the organization slug (acme-corp).

curl https://api.yggy.tech/api/v1/documents \
  -H "x-api-key: $YGGY_API_KEY" \
  -H "x-yggy-organization-id: acme-corp"

The sample reads the token from the YGGY_API_KEY environment variable. You can instead use Authorization: Bearer $YGGY_API_KEY.

Personal and organization API keys allow 5000 requests per hour. When the cap is reached, the API returns 429 with error.code RATE_LIMITED and a Retry-After header in seconds. Prefer GET /api/v1/documents/{id}/status/stream over tight status polling so ingest does not spend the quota. Document list limit is at most 500 (default 20).

A successful response has this form:

{
  "documents": [
    {
      "documentId": "0x123",
      "title": "Q4-report.pdf",
      "status": "COMPLETED"
    }
  ],
  "total": 1
}

The response can contain more fields. Use the Reference and /openapi.json on the API host for the current schema.

Caution

Do not put a token in source code, browser code, screenshots, logs, or documentation. The values above are samples and are not valid credentials.

Revoke a token

To rotate a token, create a replacement with the same required permissions. Update the client and confirm one successful request. Then open the old token actions and choose Revoke.

Revoke a token immediately when it is exposed, no longer used, or owned by a client that you cannot trust.

Inspect audit activity

1. Open Security → Audit log.
2. Filter by an API key action, such as auth.api_key.created or auth.api_key.revoked.
3. Select an event.
4. Check its result, time, actor, target, request information, and metadata.

Retry, resume, and cancel on a document write an audit event with the same actor: your signed-in user, or for API token calls { type: "api_key", id: <token id>, userId: <owner> } (never the raw token value). For an organization key, userId is the member who created it, kept for attribution only; it is empty once that member’s account is deleted.

The page shows up to the 100 most recent events. A result can be success, failure, or partial. Treat a failed event as evidence that an operation was attempted, not that it completed.