Skip to main content
Use the authorisation-code flow with S256 PKCE to request user-approved access to the Sendmux REST APIs. The user selects a team, permissions, and any required mailboxes on the consent screen.

​
Endpoints and resource

Include resource=https://sendmux.ai/api when registering a REST client and when requesting authorisation, exchanging a code, or refreshing a token. A client’s registered resource is the default when later requests omit it. The REST resource covers all three API base URLs. A token still needs the approved surface, operation scopes, and mailbox selection. Hosted MCP, A2A, and agent-registration tokens retain their separate resources; they are not interchangeable with REST OAuth tokens.

​
Register the client

Send JSON to the registration endpoint. Register a web connector’s exact HTTPS callback URL. Native clients use application_type: "native", a loopback IP callback, and token_endpoint_auth_method: "none"; the callback port may change between requests.
Store the returned client_id and any client_secret in the connector’s protected credential store. A public client uses none; never embed a client secret in distributed applications.

​
Authorisation request

Open the authorisation URL in the user’s browser. At the callback, require the original state and an iss value exactly equal to the discovered issuer. Handle an OAuth error before exchanging a code.

​
Exchange the code

Send form-encoded parameters to the token endpoint. The client authentication method must match its registration. Store access_token, refresh_token, scope, and the expiry calculated from expires_in. Send the access token as Authorization: Bearer to the API, then use its connection endpoint to validate and label the connection.

​
Permissions and mailbox selection

Use the operation’s OpenAPI security requirements for its exact scopes. Access remains limited by the current grant, client registration, authorising user’s team membership and permissions, and selected mailboxes. Removing the user or withdrawing required permissions invalidates delegated access. For mailbox operations, pass mailbox_id when the grant contains several mailboxes. The connection check and granted-mailbox listing do not require a selection. A mailbox event stream requires mailbox.read and closes by the credential’s expiry; refresh and reconnect using the documented sync flow. OAuth access tokens authenticate HTTP APIs. They are not SMTP or IMAP passwords.

​
Refresh and disconnect

Authenticate the refresh request using the registered client method. Persist the returned token pair atomically and serialise refreshes for each connection. Refresh tokens rotate; replay of a consumed token revokes the grant. After an uncertain refresh response, require a new login instead of replaying the old token. To disconnect, send token and token_type_hint=refresh_token to the revocation endpoint with the registered client authentication. Delete the saved connection after revocation succeeds. Revocation or permission changes are checked on new API requests and event-stream connections; an already-open stream closes at its credential deadline.

​
SDK and CLI use

The SDK’s access-token provider runs before each request. Your application owns token storage and refresh coordination. The CLI manages browser login, protected local profiles, refresh rotation, and logout.

Test an integration connection

Configure the GET check and response-field mapping.

SDKs

Select a client and its authentication configuration.