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, also available at the MCP-specific metadata URL. The protected resource is https://api.igeo.ai/mcp.

Follow its authorization-server pointer to authorization server metadata. Current endpoint values are:

Step 2 — Pick a method

• Workspace API key: create a key in 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:

{
  "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:

{
  "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:

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

Use the MCP initialization and read workflow or make the first REST request. 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.

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. 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 and documents the flow implemented by igeo.ai. See product Public API documentation and product MCP documentation for further context.