Build An App On Your Organization's Sign-In

This page is for developers. Your organization's sign-in is a standard OAuth 2.0 and OpenID Connect provider, so any app or tool can sign your people in with their Kamo accounts and, with their permission, work with their Kamo data through the API and the Kamo MCP server. Nothing here is specific to one vendor or one kind of app.

Before You Start

1. An administrator opens Settings, then Security, Identity & Sign-In, Connected Apps, and connects your app (see Connect An App). They get a client ID, and for a website a client secret, shown once.
2. Your app reads everything else from the discovery address on the app's card, for example https://login.yourcompany.com/.well-known/openid-configuration. Organizations without their own web address have one like https://login.kamouniverse.com/o/<organization number>/.well-known/openid-configuration. Every other address in this page starts with that same issuer.

Permissions (Scopes)

An app asks for permissions with scope. The sign-in permissions are openid (always needed), profile, email, phone, kamo.org, kamo.roles and offline_access (stay connected with a refresh token).

The data permissions below let an app use the API on someone's behalf. Each one stands for Kamo permissions the person already has. An app can never do more than the person could do in Kamo themselves: when a token is issued it only carries the data permissions whose Kamo permissions the person holds right then, and every call is checked again against what they hold at that moment. Deleting is never available to an app.

The same list, always current, is at https://api.<your domain>/api/security/oidc/scopes. A write permission also lets the app read the same kind of data.

An app can only ask for the permissions it was given. Your administrator picks them when connecting the app: the sign-in ones under What It Can See, the data ones under Work With Kamo Data, one See and one Change switch per kind of data, each showing the Kamo permission it needs. Ask them to switch on exactly the scopes you request; asking for one the app wasn't given fails with invalid_scope.

Sign Someone In (Authorization Code With PKCE)

Send the person's browser to the authorization address with a PKCE challenge:

https://login.yourcompany.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&scope=openid%20profile%20contacts.read%20offline_access
  &state=RANDOM&code_challenge=BASE64URL_SHA256_OF_VERIFIER&code_challenge_method=S256

They sign in, see what your app asks for in plain words, and press Allow. Your redirect address receives code, state and iss. Swap the code for tokens:

curl -X POST https://login.yourcompany.com/oauth/token \
  -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
  -d grant_type=authorization_code -d code=THE_CODE \
  -d redirect_uri=https://app.example.com/callback -d code_verifier=THE_VERIFIER

Apps that can't keep a secret (single-page, mobile, desktop, command-line) send client_id=YOUR_CLIENT_ID instead of -u. The answer has access_token (a Bearer token), id_token (who signed in), refresh_token (only with offline_access) and scope (what the token really carries).

Call The API

Send the access token to your organization's API address:

curl https://api.yourcompany.com/api/contacts -H "Authorization: Bearer ACCESS_TOKEN"

• 401 with WWW-Authenticate: Bearer error="invalid_token": the token expired, was revoked, or the person no longer has access. Refresh it or sign in again.
• 403 with error="insufficient_scope", scope="contacts.write": the token doesn't carry the permission that address needs. Ask for it at sign-in.
• Reading (GET) needs the read permission of that kind of data; anything that changes data needs write.

Let Your App Register Itself

If an administrator turned on Let Apps Connect Themselves (see that article), an app can register without anyone typing it in, using the standard registration request (RFC 7591). The address is in the discovery document as registration_endpoint:

curl -X POST https://login.yourcompany.com/oauth/register -H "Content-Type: application/json" -d '{
  "client_name": "My Tool", "redirect_uris": ["http://127.0.0.1:33418/callback"],
  "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"],
  "scope": "openid contacts.read leads.read offline_access" }'

The answer has your client_id (and a client_secret for apps that keep one) and kamo_status. PENDING means an administrator must approve it in Connected Apps before anyone can sign in; until then signing in shows "This app is waiting for approval". When registration is off the address answers 404.

Connect An AI Assistant Or MCP Client

The Kamo MCP server is at https://api.yourcompany.com/mcp. Any MCP client that supports MCP authorization can connect: on its first call it gets 401 with a WWW-Authenticate header pointing at https://api.yourcompany.com/.well-known/oauth-protected-resource/mcp, which names your organization's sign-in as the authorization server. The client then registers itself (if allowed) or uses a client ID an administrator gave you, signs the person in as above, and sends Authorization: Bearer ACCESS_TOKEN on every MCP request. The tools it can use are exactly the ones the person's permissions and the token's scopes allow.

Sign In On A TV Or Device

Devices without a keyboard use the device sign-in (RFC 8628). The app needs the TV Or Device type, or the device sign-in turned on:

curl -X POST https://login.yourcompany.com/oauth/device_authorization -d client_id=YOUR_CLIENT_ID -d "scope=openid profile"

Show the person the user_code (like WDJB-MJHT) and the verification_uri, then poll every interval seconds:

curl -X POST https://login.yourcompany.com/oauth/token -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d device_code=THE_DEVICE_CODE -d client_id=YOUR_CLIENT_ID

Keep polling while the answer is authorization_pending; on slow_down wait 5 seconds longer each time. The code lasts 10 minutes.

When Someone Leaves

Removing a person's access in Kamo ends their tokens: the API and the MCP server stop answering for them at once (within a minute), and refresh fails. People can also remove an app themselves in My Profile, Apps With Access.