OAuth: "Add to Missived" and "Sign in with Missived"

Missived is an OAuth 2.1 and OpenID Connect provider. Other services can use it two ways:

• Add to Missived installs your app's bot in an org the person chooses. The tokens act as the bot.
• Sign in with Missived lets a person sign in to your service. The tokens act as that person, within the scopes they allowed.

Register your app

Any org can make an app under Org Settings → Integrations → Apps & bots and open its OAuth panel:

• Client type: confidential (your server keeps a client secret, shown once; rotate it from the same panel) or public (a browser, desktop or mobile app with no secret).
• Redirect URIs: matched exactly. https anywhere; http only on localhost, 127.0.0.1 or [::1] (any port); or a reverse-domain custom scheme such as com.example.app:/callback.

The client id is the app id. Until the platform approves your app, only members of the org that made it can connect it, which is your test loop. To open it to every org, get it listed in the app gallery.

Endpoints

Discovery is at https://api.missived.com/oauth/.well-known/openid-configuration (also /.well-known/oauth-authorization-server). The issuer is https://api.missived.com/oauth.

The flow

Authorization code with PKCE (S256), required of every client. There is no implicit, password or client-credentials grant, and no dynamic registration. Authorization responses carry iss.

1. Send the person to /oauth/auth with response_type=code, client_id, redirect_uri, scope, state, code_challenge and code_challenge_method=S256.
2. They sign in to Missived (if they aren't already) and see a consent screen: your app, who made it, what it will be able to do, and, for an install, which org.
3. Missived redirects back with code and state (or error).
4. Exchange the code at /oauth/token with the code_verifier. A confidential client authenticates with its secret, in the body or with HTTP Basic.

Scopes decide which of the two you get:

• scope=bot channels:read messages:write … asks for an install. The person must be an Owner or Admin, or have Manage integrations, in the org they pick. Your bot is installed with those scopes; doing it again re-grants them. /v1/me with the token says kind: "app" and the install's id. The bot sees only the channels people add it to and never direct messages.
• Without bot, it's a sign-in: the tokens act as the person, within the granted scopes, in the orgs that let members connect apps. openid email profile adds an ID token with sub, email and name.

You may pass resource=https://api.missived.com/v1 to bind the tokens to the API.

Tokens

• Access tokens are opaque, msv_oat_…, valid for 1 hour. Use them as a bearer on /v1 exactly like an API token; rate limits count per token.
• Refresh tokens are msv_ort_… and rotate on every use: store the new one every time. Using an old refresh token again revokes the whole connection.
• People can disconnect your app at any time in Settings → Connected apps; admins can remove an install. Your tokens then stop working at once.

For org admins

• Org Settings → Integrations → Connected apps lists the org's installs made through OAuth and members' sign-in connections, with the Members may connect apps setting: Off, Sign-in only (the default) or Sign in and act as them. Installing a bot always needs Manage integrations.
• Business orgs can allow only listed app ids.

Errors reach your redirect URI (error, error_description, state) when the request is valid enough to know where to send them; otherwise Missived shows an error page.