---
title: "igeo.ai authentication and permissions"
description: "Authenticate igeo.ai integrations with workspace API keys or MCP OAuth, and understand roles, scopes, and retry limits."
url: "https://www.igeo.ai/developers/auth/"
language: "en"
---

BUILD WITH igeo.ai[Read as Markdown ↗](https://www.igeo.ai/developers/auth.md)

# igeo.ai authentication and permissions

Authenticate an integration for one authorized igeo.ai workspace. Public marketing pages and these guides are readable without a key. Private REST and MCP operations require credentials, current workspace access, and permission for the requested action.

## Goal and prerequisites

Use an existing igeo.ai account and an active workspace. Active members can manage API keys; MCP tools and resources require owner, admin, or editor access. OAuth consent also requires one of those roles. For an OAuth client, prepare an exact callback URL and a PKCE S256 implementation.

## Step 1 — Discover

Read the API host's [protected resource metadata](https://api.igeo.ai/.well-known/oauth-protected-resource), also available at the [MCP-specific metadata URL](https://api.igeo.ai/.well-known/oauth-protected-resource/mcp). The protected resource is `https://api.igeo.ai/mcp`.

Follow its authorization-server pointer to [authorization server metadata](https://api.igeo.ai/.well-known/oauth-authorization-server). Current endpoint values are:

| Purpose | Endpoint |
| --- | --- |
| Client registration | `POST https://api.igeo.ai/register` |
| User authorization | `GET https://api.igeo.ai/oauth/authorize` |
| Code exchange | `POST https://api.igeo.ai/oauth/token` |
| MCP requests | `POST https://api.igeo.ai/mcp` |

## Step 2 — Pick a method

-   **Workspace API key:** create a key in [MCP & API keys](https://app.igeo.ai/mcp-api-keys). Copy the secret once and retain the workspace ID from the generated configuration. Continue to Step 6.
-   **OAuth for MCP:** let a compatible client's OAuth implementation complete Steps 3–5. The server advertises authorization-code grants, PKCE `S256`, and token endpoint authentication methods `client_secret_post` and `none`.

OAuth metadata scopes describe the OAuth flow. They are distinct from the API-key operation scopes listed below. A website session JWT is not an MCP API key.

## Step 3 — Register an OAuth client

If your client needs dynamic registration, send this JSON body to the advertised registration endpoint with `Content-Type: application/json`. Replace the example callback with your client's callback URL:

```json
{
  "redirect_uris": ["https://client.example/callback"],
  "client_name": "Workspace integration",
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code"],
  "response_types": ["code"]
}
```

Retain the returned `client_id`. A client registering with `client_secret_post` must also protect its returned `client_secret`. This registers an OAuth client; it does not create a user, workspace, or grant to customer data.

## Step 4 — Authorize with user consent

Generate and retain a PKCE verifier, its S256 challenge, and a fresh state value. Open the advertised authorization endpoint with `response_type=code`, `client_id`, the registered `redirect_uri`, `code_challenge`, `code_challenge_method=S256`, and `state`.

The user signs in, selects an eligible workspace, and authorizes the connection. Keep that workspace ID for subsequent requests. The callback returns `code` and the supplied `state`; validate state before exchanging the code.

There is no separate WorkOS claim ceremony. The current server does not advertise an `agent_auth` identity, claim, or events endpoint, anonymous registration, or an ID-JAG exchange. Use the supported sign-in and workspace-consent flow.

## Step 5 — Exchange the authorization code

Send the callback code and original verifier to `POST https://api.igeo.ai/oauth/token`. The endpoint accepts this JSON body with `Content-Type: application/json`:

```json
{
  "grant_type": "authorization_code",
  "code": "<AUTHORIZATION_CODE>",
  "redirect_uri": "https://client.example/callback",
  "client_id": "<CLIENT_ID>",
  "code_verifier": "<ORIGINAL_PKCE_VERIFIER>"
}
```

For `client_secret_post`, also include `client_secret`. Keep the returned `access_token` private and honor `expires_in`. The advertised grant is `authorization_code`; a refresh-token flow is not advertised. When access expires, use the client's supported authorization flow again.

## Step 6 — Use the credential

For MCP, send the OAuth access token or workspace API key. Public REST examples use a workspace API key. Both require the selected workspace:

```http
Authorization: Bearer <ACCESS_TOKEN_OR_API_KEY>
X-Workspace-Id: <YOUR_WORKSPACE_ID>
```

Use the [MCP initialization and read workflow](https://www.igeo.ai/developers/mcp/) or make the [first REST request](https://www.igeo.ai/developers/api/). Keep credentials in a private local environment or server-side secret store.

If a client accepts only a connection URL, the product can generate `mcp_token` and `workspace_id` query parameters. Treat that entire URL as a secret because logs and browser history can retain it. Prefer headers where supported; a session JWT is not accepted as the query-string MCP key.

## Permissions and API key scopes

Public REST access is included for every workspace. Keys inherit the creator's current workspace access. Public REST reads must pass endpoint access checks; writes and deletes also require owner, admin, or editor access. MCP tools and resources require one of those roles, including read tools.

| API key scope | Public REST methods |
| --- | --- |
| `read` | GET |
| `write` | POST, PUT, PATCH |
| `delete` | DELETE |
| `mcp:full` | All supported operations, subject to route and role checks |

Use the smallest scope set needed. A scope cannot expose private endpoints or override workspace permissions.

## Errors and retries

OAuth errors include `invalid_request`, `invalid_client`, `invalid_grant`, and `unsupported_grant_type`. Check required fields, callback registration, client authentication, code expiry, and the original verifier. Restart authorization when a code has expired or was already consumed.

For authenticated calls, investigate `401` credentials or workspace mismatches and `403` role, scope, Origin, or route restrictions. On `429`, honor `Retry-After` and inspect `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and their `-Month` variants. Limits are configurable. Retry transient reads with bounded backoff and jitter; reconcile state before repeating a timed-out write. No universal idempotency-key contract is specified here.

## Revocation

Revoke a workspace key through [MCP & API keys](https://app.igeo.ai/mcp-api-keys). Expired or revoked keys cannot authenticate. OAuth connections create an underlying workspace key; revoking that key also prevents its access token from authenticating. The server does not advertise an RFC 7009 token revocation endpoint or agent revocation-event endpoint.

The walkthrough uses the [auth.md reference's discovery terminology](https://github.com/workos/auth.md/blob/main/AUTH.md) and documents the flow implemented by igeo.ai. See [product Public API documentation](https://app.igeo.ai/docs/public-api) and [product MCP documentation](https://app.igeo.ai/docs/mcp) for further context.

---

Source: https://www.igeo.ai/developers/auth/

[Documentation index](https://www.igeo.ai/llms.txt) · [Developer documentation](https://www.igeo.ai/developers/)