Skip to main content
Read Orq.ai documentation and use the documentation MCP server at https://docs.orq.ai/mcp without authentication. The steps below apply to agents calling the Orq.ai API or the workspace MCP server at https://my.orq.ai.

​
Discover

  • Capability catalog: https://docs.orq.ai/.well-known/ai-catalog.json
  • OpenAPI specification: https://docs.orq.ai/openapi.json, listing operations and their authentication requirements
  • API resource metadata: https://my.orq.ai/.well-known/oauth-protected-resource
  • MCP resource metadata: https://my.orq.ai/.well-known/oauth-protected-resource/v2/mcp
  • Authorization server metadata: https://my.orq.ai/.well-known/oauth-authorization-server/v2/auth/mcp
  • OAuth issuer: https://my.orq.ai/v2/auth/mcp

​
Pick a method

  • API key: for automation calling the API or the MCP server without a user present. A person provisions the key.
  • OAuth: for MCP clients acting on behalf of a signed-in user. Supported grants are authorization_code and refresh_token, with PKCE S256 required.
Agent self-registration and anonymous credentials are not supported. Every credential belongs to an Orq.ai user or workspace.

​
Register

For an API key:
  1. Create an account at Sign up, or sign in to an existing workspace.
  2. Create a project-scoped API key. Use a service account key for production automation; creating one requires a workspace admin.
  3. Grant the permissions required by the agent and store the key securely.
For OAuth, register the MCP client at https://my.orq.ai/v2/auth/mcp/register. Client registration does not create an Orq.ai user or workspace.

​
Claim

API keys need no claim step. For OAuth, send the user to the authorization endpoint from the authorization server metadata. The user completes the browser sign-in and workspace consent, and the client receives an authorization code at its redirect URI.

​
Exchange

Exchange the authorization code, with the PKCE verifier, at https://my.orq.ai/v2/auth/mcp/token. Use the refresh_token grant at the same endpoint to obtain a new access token.

​
Use the credential

Send the API key or access token in the request header:
Connect an OAuth-capable MCP client to https://my.orq.ai/v2/mcp; see the workspace MCP guide for client setup.

​
Errors

  • A request to https://my.orq.ai/v2/mcp without credentials returns 401 with a WWW-Authenticate header whose resource_metadata points at the MCP resource metadata.
  • API requests with a missing, invalid, expired, or under-permissioned key return the codes in Authentication errors.
  • The token, registration, and revocation endpoints return standard OAuth error codes such as invalid_request, invalid_client, invalid_grant, and unsupported_grant_type.

​
Revocation

Revoke OAuth tokens at https://my.orq.ai/v2/auth/mcp/revoke (RFC 7009). Manage, revoke, or replace API keys through Settings > API Keys; see Secrets management for rotation instructions.