Public and legacy OAuth clients

This reference covers dynamically registered MCP connectors and existing public native and legacy OAuth clients. They use authorization code flow with S256 PKCE. Public clients have no embedded client secret; hosted connectors can register with a server-side client secret.

Building a SaaS that customer companies install? Use Applications and the confidential company-app guide instead. Dashboard-created applications require resource-specific scopes and server-side client authentication; the secretless api examples here do not apply to them.

The existing public-client api scope and first-party api/web behavior remain compatible. web is reserved for first-party browser sessions, not dynamically registered clients. API keys keep their existing permissions. See MCP for connector setup and available tools.

Discovery metadata

Fetch these JSON documents from the Phone.inc origin (https://app.phone.inc in production), not your own application's origin:

  • GET /.well-known/oauth-authorization-server — issuer, authorization, token, revocation, and registration endpoints; supported response types, grants, PKCE methods, client authentication methods, and scopes.
  • GET /.well-known/oauth-protected-resource — the root resource identifier, linked authorization server, Bearer methods, and scopes.
  • GET /.well-known/oauth-protected-resource/mcp — the same protected-resource metadata for resource: https://app.phone.inc/mcp.

The issuer matches the host called. The root protected resource uses that host as resource; the MCP document includes /mcp. Authorization-server metadata advertises response_types_supported: ["code"], grant_types_supported: ["authorization_code", "refresh_token"], and code_challenge_methods_supported: ["S256"]. Client authentication methods are none, client_secret_basic, and client_secret_post. Protected-resource documents advertise bearer_methods_supported: ["header"].

The shared scopes_supported list contains api and the 23 company-app scopes. It describes the server, not permissions available to every client: dynamic registration issues clients scoped to api, while company-owned apps use their enabled resource scopes.

Register an OAuth client

POST /oauth/register implements RFC 7591 dynamic registration for MCP connectors. Send JSON. The following example registers a public client:

Registration

POST
/oauth/register
curl https://app.phone.inc/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"My MCP connector","redirect_uris":["http://127.0.0.1:8765/callback"],"token_endpoint_auth_method":"none"}'

Response

{
  "client_id": "a1b2c3d4e5f6g7h8i9j0",
  "client_id_issued_at": 1730895600,
  "redirect_uris": ["http://127.0.0.1:8765/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "client_name": "My MCP connector",
  "scope": "api"
}

Dynamically registered clients are always scoped to api and show consent. Dynamic registration does not create a company-owned SaaS application or grant first-party privileges.

Choose token_endpoint_auth_method according to where the client runs:

  • none creates a public client without a client_secret. For compatibility with existing clients, omitting the method also selects none; send it explicitly in new integrations.
  • client_secret_basic or client_secret_post creates a confidential client for a hosted connector. The response echoes the selected method and includes a generated client_secret and client_secret_expires_at: 0 (no scheduled expiry). Store the secret securely on your server. Phone.inc stores only its hash and sends registration responses with Cache-Control: no-store.

Confidential clients must authenticate code exchange, refresh, and revocation requests using their secret. The registration response echoes the requested method, but does not restrict the client to that transport: both HTTP Basic and client_id/client_secret form fields are accepted for either confidential registration. Use only one method per request. Both require the same valid secret; neither permits secretless authentication. S256 PKCE is required in addition to the secret for code exchange. Existing public registrations remain public; adding support for confidential registration does not change their credentials.

Register exact redirect URIs. HTTPS callbacks and loopback HTTP on 127.0.0.1, localhost, or [::1] with any port are supported. Custom schemes are not accepted by dynamic registration; they are only available to manually registered first-party native clients. These rules differ from company-owned application callbacks, which do not accept localhost.

Authorize with PKCE

Generate a fresh random verifier and state for each request. The challenge is base64url-encoded SHA-256 of the verifier, without padding. Keep the verifier and state securely until the callback. Open this authorization URL in the user's browser, substituting your registered client ID, exact callback, and freshly generated state and challenge:

https://app.phone.inc/oauth/authorize?response_type=code&client_id=your_client_id&redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback&scope=api&state=random_csrf_token&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256

All public clients and dynamically registered confidential clients require PKCE with code_challenge_method=S256. The user signs in and approves access on behalf of the authenticated employee. The callback includes code and state, or error=access_denied and state on denial. Validate state before exchanging the code.

Exchange the code

Within 10 minutes, send form-encoded fields to /oauth/token. The redirect URI must match the authorization request exactly. Public clients send their client ID and verifier without a client secret:

curl https://app.phone.inc/oauth/token \
  --data-urlencode grant_type=authorization_code \
  --data-urlencode "client_id=$PHONE_INC_CLIENT_ID" \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode redirect_uri=http://127.0.0.1:8765/callback \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"

Response

{
  "access_token": "access_token_value",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_token_value",
  "scope": "api",
  "created_at": 1730895600
}

Use and refresh tokens

Send Authorization: Bearer <access_token> to /api/v1/* or the MCP endpoint. Tokens act on behalf of the authorizing employee. Access tokens last one hour; refresh tokens are valid for 30 days from issue. Store tokens in secure platform storage, never in source code or browser localStorage.

Public clients refresh without a secret:

curl https://app.phone.inc/oauth/token \
  --data-urlencode grant_type=refresh_token \
  --data-urlencode "client_id=$PHONE_INC_CLIENT_ID" \
  --data-urlencode "refresh_token=$PHONE_INC_REFRESH_TOKEN"

Confidential clients authenticate with their secret, for example using HTTP Basic:

curl https://app.phone.inc/oauth/token \
  --user "$PHONE_INC_CLIENT_ID:$PHONE_INC_CLIENT_SECRET" \
  --data-urlencode grant_type=refresh_token \
  --data-urlencode "refresh_token=$PHONE_INC_REFRESH_TOKEN"

The response has the same token fields as code exchange. Store the newly issued refresh token and discard the previous one. The previous refresh token is invalidated when the new access token is first used on an authenticated API or MCP request, not immediately when the refresh response is issued. An invalid, expired, or revoked API token returns 401; refresh and retry once, or restart authorization if refresh fails. OAuth endpoint errors use error and error_description; see OAuth errors.

Revoke a token

Public clients send their client ID:

curl https://app.phone.inc/oauth/revoke \
  --data-urlencode "client_id=$PHONE_INC_CLIENT_ID" \
  --data-urlencode "token=$PHONE_INC_ACCESS_TOKEN"

Confidential clients also authenticate with their secret:

curl https://app.phone.inc/oauth/revoke \
  --user "$PHONE_INC_CLIENT_ID:$PHONE_INC_CLIENT_SECRET" \
  --data-urlencode "token=$PHONE_INC_ACCESS_TOKEN"

Send an access or refresh token. Successful revocation returns 200 OK, including for unknown tokens, per RFC 7009. Do not apply the confidential company-app installation lifecycle to public clients; company-app revocation requires client authentication and disconnects the whole installation.

First-party native compatibility

Native builds installed side by side should use distinct callback schemes and register each exact redirect URI with their client. Standard Phone.inc mobile builds keep phoneinc://oauth/callback. Android previews use inc.phone.preview.pr<PR>://oauth/callback, accepted only for our first-party public mobile client. These custom schemes are not accepted by dynamic registration or company-owned applications.

Token exchange must use the same redirect URI as authorization. Android preview exchanges require an exact string match, including rejecting added query parameters. First-party clients retain their existing consent behavior; dynamic registration cannot opt a client into first-party status.