Start here · v1

OAuth authentication

Use a registered public client and authorization code with PKCE S256. There is no client secret, API key or client-credentials grant.

Discovery and addresses

Register a public client

Use My applications with an approved account. Register 1–5 exact redirect URIs and a descriptive name. HTTPS callbacks cannot contain user information or fragments. Native clients can register an HTTP loopback IP callback; its port must match registration exactly. This release targets backend and native applications and does not enable browser cross-origin API calls.

Create a pending authorization

Generate a cryptographically random state and a new random PKCE verifier for each attempt. Keep both in a short-lived, one-use pending record. Send the SHA-256 base64url challenge, never the verifier, in the authorization URL.

https://orchesphere.ai/oauth/authorize
  ?response_type=code
  &client_id=orch_app_YOUR_REGISTERED_ID
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A8788%2Fcallback
  &resource=https%3A%2F%2Fapi.orchesphere.ai
  &scope=orchesphere.read%20offline_access
  &state=<fresh_random_state>
  &code_challenge=<base64url_sha256_of_verifier>
  &code_challenge_method=S256

On the callback, require an unexpired pending record, an exact state match and the expected issuer. Reject duplicate parameters, unexpected callback paths and reused callbacks. Handle a user denial without attempting a token exchange.

Exchange the code

POST https://orchesphere.ai/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=orch_app_YOUR_REGISTERED_ID
&code=<one_time_code>
&redirect_uri=http%3A%2F%2F127.0.0.1%3A8788%2Fcallback
&resource=https%3A%2F%2Fapi.orchesphere.ai
&code_verifier=<original_verifier>

Send the fields as one form-encoded body. Do not send a client secret or an Authorization header to the token endpoint. Code lifetime is 120 seconds; access-token lifetime is 300 seconds. Form bodies are limited to 16 KiB.

Refresh and disconnect

POST https://orchesphere.ai/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=orch_app_YOUR_REGISTERED_ID
&resource=https%3A%2F%2Fapi.orchesphere.ai
&refresh_token=<current_refresh_token>

When offline_access is approved, the refresh token rotates on every successful refresh. Replace the saved token pair atomically. Serialize refresh operations; reusing an old refresh token revokes the grant. A new authorization is required after the 30-day grant expires or access/security is revoked.

POST https://orchesphere.ai/oauth/revoke
Content-Type: application/x-www-form-urlencoded

client_id=orch_app_YOUR_REGISTERED_ID
&token=<refresh_token>
&token_type_hint=refresh_token

Revoking an application prevents future authorization and invalidates its grants. Disconnecting a user’s connected client revokes that user’s grant. Already saved work remains subject to current authorization checks.

Token handling

Keep credentials in server memory or an appropriate encrypted application store. Keep tokens and PKCE verifiers out of URLs. The authorization code returns in the registered callback query; do not log or share that callback URL. Keep codes, tokens and verifiers out of logs, analytics, public repositories and localStorage. The example stores them only in memory and prints only success/status information.