Skip to main content
Direct API authorization requires the corresponding Trackly app and external API rollout. Registration preview generation also requires the jobs worker rollout so it recognizes direct API grants. This guide describes the implemented connection contract, not confirmation that it is enabled for your account. Confirm availability with support.
Custom agents can use OAuth directly without running MCP or obtaining a service secret. The owner signs in or creates a Trackly account, verifies email and any required second factor, and approves the requested permissions in Trackly. An umbrella account is not required. Use issuer https://app.tracklysms.com; discover its endpoints through https://app.tracklysms.com/.well-known/oauth-authorization-server. Public clients use S256 PKCE and token_endpoint_auth_method: "none".

​
Connect the client

  1. Register the client at POST https://app.tracklysms.com/oauth/register with JSON containing client_name, your exact redirect_uris, grant_types: ["authorization_code", "refresh_token"], response_types: ["code"], and token_endpoint_auth_method: "none". Store the returned client_id. Use only redirect URIs your client controls.
  2. Generate a fresh private PKCE verifier and its S256 challenge, plus an unpredictable state. Open /oauth/authorize in the owner’s browser with response_type=code, client_id, redirect_uri, code_challenge, code_challenge_method=S256, state, resource=https://api.tracklysms.com/api, and scope=trackly.registration. Add trackly.agent only if approved SMS capability is also needed; registration permission does not authorize sending.
  3. Validate the callback state and issuer before accepting the code. Exchange it at /oauth/token using form encoding and exactly grant_type=authorization_code, client_id, code, redirect_uri, code_verifier, and the same resource.
  4. Store the access and refresh tokens in private client credential storage. Send the access token as Authorization: Bearer … to the API. Never put tokens, verifiers, or provider credentials in chat, logs, source control, or tool arguments.
Authorization requests expire after 10 minutes and codes after 2 minutes. Direct API access tokens last at most 15 minutes; follow the returned expires_in. Grants last at most 7 days and can end sooner through revocation or changed account authority. trackly.registration permits account/setup reads and the four registration preparation operations. Requests remain bound to the consenting account, grant, and dedicated credential. An existing SMS-only connection needs fresh consent for registration. Owner publication, optional Entri provider consent, and final paid registration submission remain separate human decisions.

​
Refresh and disconnect

Send form-encoded grant_type=refresh_token, client_id, refresh_token, and the exact original resource to /oauth/token. Refresh tokens rotate and are single-use: replace both stored tokens together. Do not add scopes or switch audiences during refresh. After an uncertain refresh outcome, do not repeatedly replay the old refresh token; reconnect if the client cannot recover its stored replacement. Disconnect through /oauth/revoke with form-encoded client_id and token. A public client does not supply a client secret. Revocation or expired authority requires a new owner-approved connection.

​
Call registration directly

The following assumes your client has stored the bearer privately in TRACKLY_API_ACCESS_TOKEN; never paste its value into a conversation. Keep the operation key stable when recovering the same creation.
Continue with read, update, and private preview. Follow the owner review and recovery workflow. The MCP resource remains https://mcp.tracklysms.com/mcp. Tokens issued for that audience cannot be sent directly to the API; Trackly’s MCP adapter uses its separate exchange path, whose API tokens remain limited to 60 seconds. Direct REST clients use the API resource above and need no adapter exchange secret.