Use these endpoints to discover the service, authorize a user and call MCP. REST uses resource https://api.orchesphere.ai; MCP uses https://orchesphere.ai/mcp.
Find the issuer, OAuth endpoints and supported authorization behavior.
Authentication
No Bearer token required.
Inputs
No request body.
Result
JSON issuer=https://orchesphere.ai with authorization_endpoint=/oauth/authorize, token_endpoint=/oauth/token and revocation_endpoint=/oauth/revoke on that issuer; code response type; authorization_code and refresh_token grant types; S256 PKCE; public-client authentication method none; supported scopes and authorization-response issuer support.
Boundaries
The server advertises official client metadata-document support as well as registered applications; this is not unrestricted URL-based client registration.
No public dynamic-registration or JWKS endpoint is advertised. Register an application through signed-in API & developers.
Metadata may include an internal scope unavailable to registered developer applications.
Authorize an application
GEThttps://orchesphere.ai/oauth/authorize
Let a signed-in user review and approve an application’s resource and scopes using Authorization Code with S256 PKCE.
Authentication
The user completes OrcheSphere browser sign-in, current account-security requirements and explicit consent.
Inputs
Browser query: response_type=code, registered client_id, exact redirect_uri, explicit resource, requested scope, fresh random state, code_challenge and code_challenge_method=S256. Keep the original verifier in the client’s one-use pending authorization record.
Result
The browser shows sign-in or consent. On approval, the registered callback receives code, the original state and iss=https://orchesphere.ai. On denial, it receives error=access_denied, state and iss. The authorization code expires after 120 seconds.
Boundaries
The exact resource is https://api.orchesphere.ai for REST or https://orchesphere.ai/mcp for MCP. Scope approval grants no company membership.
Registered applications must use an exact registered HTTPS or HTTP loopback-IP callback, including the port. Official Codex metadata-based callbacks have a separate ephemeral-loopback-port rule.
The authorization request is not a client-credentials grant or a JSON API. The server-generated consent form is browser-session-bound; third-party clients must not call it directly.
Validate state, issuer, callback path and a fresh pending record before exchanging a code. Reject duplicate or reused callback parameters.
Exchange or refresh tokens
POSThttps://orchesphere.ai/oauth/token
Exchange a one-use authorization code for an access token, or rotate tokens for an existing offline authorization.
Authentication
Public client with client_id and PKCE for code exchange. Do not send an Authorization header, client secret or client assertion.
Inputs
application/x-www-form-urlencoded. Code exchange: grant_type=authorization_code, client_id, code, exact redirect_uri, exact resource and original code_verifier. Refresh: grant_type=refresh_token, client_id, exact resource and current refresh_token.
Result
HTTP 200 JSON access_token, token_type, expires_in and scope. A refresh_token is returned only when offline_access was approved. Access-token lifetime is 300 seconds; refresh rotates the token pair within the original 30-day grant. Errors use OAuth error and error_description.
Boundaries
Forms are limited to 16KiB. Duplicate parameters and oversized field values are rejected.
Use the same exact resource during authorization, code exchange and refresh. REST tokens cannot call MCP and MCP tokens cannot call REST.
Serialize refresh requests and replace the saved pair atomically. Reusing an already-rotated refresh token revokes its grant.
Expiry, revocation, account-security changes and current company permissions still apply. offline_access is not a guarantee of unattended or permanent access.
Revoke an authorization
POSThttps://orchesphere.ai/oauth/revoke
Disconnect the grant associated with an application’s access or refresh token.
Authentication
Public client_id and the token to revoke. No Authorization header or client secret.
Inputs
application/x-www-form-urlencoded with client_id and token. token_type_hint may be sent but the current implementation does not use it to select the token type.
Result
Empty HTTP 200. A matching token revokes its authorization grant; an unknown token is a successful no-op. Later use of tokens from a revoked grant is rejected.
Boundaries
Forms are limited to 16KiB. The client must be recognized.
Revocation does not delete saved jobs/tasks or disconnect provider credentials. Already saved work remains subject to current authorization checks.
Revoking this user grant differs from revoking a registered application itself through API & developers.
Call the MCP interface
POSThttps://orchesphere.ai/mcp
Initialize an MCP connection, discover permitted tools and call them with explicit company context.
Authentication
Authorization: Bearer token approved for the exact resource https://orchesphere.ai/mcp.
Inputs
JSON-RPC 2.0 with initialize, notifications/initialized, ping, tools/list or tools/call. For calls, supply params.name and params.arguments matching the tool schema. Send Content-Type: application/json.
Result
initialize returns protocolVersion, tool capabilities, serverInfo and instructions; initialized notification returns empty 202; ping returns an empty result; tools/list returns scope-filtered definitions. Successful calls return result.content, result.structuredContent and isError:false. Tool/action failures commonly return HTTP 200 with isError:true.
Boundaries
Supported protocol versions are 2025-06-18, 2025-03-26 and 2024-11-05. This endpoint does not use SSE transport or a session ID.
The JSON request body is limited to 24,000 bytes; batches are not supported. A malformed or oversized request produces the current generic parse-error response.
Missing/invalid authorization produces HTTP 401. Insufficient tool scope produces HTTP 403 with WWW-Authenticate. Inspect isError even when HTTP is 200.
Tools/list reflects approved OAuth scopes, not proof of authority for a particular company. Every call still checks current identity and company/service/portal permissions.
The ordinary MCP list payloads do not carry REST pagination metadata. Job lists return the latest 100 permitted jobs. No separate outputSchema is advertised by these tool definitions.
Browser implementation endpoints
Sign-in forms, consent submissions, account settings and provider callbacks belong to the website flow. They are not public integration endpoints. Create registered applications through the API & developers portal; dynamic client registration and client-credentials grants are not supported.