Skip to content
iAM360

Guides

Authentication

The server takes OAuth 2.1 access tokens from iAM360's sign-in. MCP clients that follow the MCP authorization spec find everything below on their own; this page is for building or debugging one.

How a client connects

  1. Call without a token. The server answers 401, and its WWW-Authenticate header names the scope and where the resource metadata is.

    Response
    HTTP/2 401www-authenticate: Bearer error="invalid_token", error_description="No authorization provided", scope="fitness", resource_metadata="https://app.iam360.ai/.well-known/oauth-protected-resource/api/mcp"

  2. Read the resource metadata (RFC 9728). It names the authorization server and the fitness scope.

    app.iam360.ai/.well-known/oauth-protected-resource/api/mcp
    {  "resource": "https://app.iam360.ai/api/mcp",  "authorization_servers": ["https://clerk.iam360.ai"],  "scopes_supported": ["fitness"],  "bearer_methods_supported": ["header"],  "resource_name": "iAM360",  "resource_documentation": "https://app.iam360.ai/docs/mcp",  "resource_policy_uri": "https://app.iam360.ai/privacy",  "resource_tos_uri": "https://app.iam360.ai/terms"}

  3. Read the authorization server metadata (RFC 8414) at https://clerk.iam360.ai/.well-known/oauth-authorization-server. Clients built on the 2025-03-26 spec can read the same document at https://app.iam360.ai/.well-known/oauth-authorization-server.

    Authorization server metadata, abridged
    {  "issuer": "https://clerk.iam360.ai",  "authorization_endpoint": "https://clerk.iam360.ai/oauth/authorize",  "token_endpoint": "https://clerk.iam360.ai/oauth/token",  "registration_endpoint": "https://clerk.iam360.ai/oauth/register",  "revocation_endpoint": "https://clerk.iam360.ai/oauth/token/revoke",  "scopes_supported": [    "openid", "profile", "email", "public_metadata", "private_metadata",    "offline_access", "fitness"  ],  "code_challenge_methods_supported": ["S256"],  "token_endpoint_auth_methods_supported": [    "client_secret_basic", "none", "client_secret_post"  ],  "client_id_metadata_document_supported": true}

  4. Identify the client. Register with Dynamic Client Registration (RFC 7591) at the registration_endpoint, or use the URL of a Client ID Metadata Document as the client_id. The consent screen shows the name the client gives there.

  5. Send the person to sign in with PKCE (S256), the fitness scope, plus offline_access for a refresh token, and resource set to the server URL (RFC 8707). They sign in to iAM360 and choose Allow.

    Authorization request
    GET https://clerk.iam360.ai/oauth/authorize  ?response_type=code  &client_id=<client id>  &redirect_uri=<redirect uri>  &scope=fitness%20offline_access  &resource=https%3A%2F%2Fapp.iam360.ai%2Fapi%2Fmcp  &code_challenge=<S256 challenge>  &code_challenge_method=S256  &state=<random value>

  6. Exchange the code at the token_endpoint and send the access token on every request.

    Request headers
    POST https://app.iam360.ai/api/mcpAuthorization: Bearer <access token>Content-Type: application/jsonAccept: application/json, text/event-stream

Scopes

fitness
Read and update the person's fitness data. Required: a token without it gets HTTP 403 with error="insufficient_scope", so the client asks the person again.
offline_access
A refresh token, so the client can get new access tokens without asking the person again.

Access tokens

  • Signed JWTs, checked on every call: signature, expiry, and that aud is this server. A token issued for another server is refused with 401.
  • They expire, currently after about a day. Use the refresh token to get a new one.
  • Send them in the Authorization header only, never in a URL or a cookie. Browser-based clients may call from any origin; the WWW-Authenticate, Mcp-Session-Id and MCP-Protocol-Version headers are readable cross-origin.
  • Revoking a refresh token at the revocation_endpoint stops new access tokens; one already issued works until it expires. To cut access at once, the person turns the assistant off in Settings, and every call is refused within a minute.