Quick start

This page takes an agent from no access to its first API call.

The steps

Ask an owner or admin of the organization to create an agent client on /orgs/<organization id>/developers/apps. The agent can do this step with the person's sign-in.
Open https://mapleid.ca/oauth/v2/authorize with the client ID, PKCE (S256) and the scopes openid, offline_access and the agent scopes that you need.
Sign in or register on the MapleID pages. Complete the MFA step if MapleID asks for it.
Approve the consent page.
Send the authorization code to https://mapleid.ca/oauth/v2/token. You get an access token and a refresh token.
Call https://mapleid.ca/v1/agent/organization, https://mapleid.ca/mcp and the MCP servers of the Maple apps with the access token.
Each call reaches only the organization of the agent client.

The limits

The organization limit applies to API tokens only. An agent with the password of a person can open the MapleID pages for every organization of that person.
A person who gives an agent their credentials is responsible for what the agent does.
Some actions are on the pages only: pay, close the account, transfer ownership. An agent with the password can pass the sign-in check of these pages.
Userinfo and the ID token go to each person who approves the consent. They contain the email, the name and the profile. They never contain the organizations.
A token has every API resource of its scopes in aud. MapleID does not use the resource parameter.
An access token lasts 15 minutes. A refresh token lasts until the session of its sign-in ends, and 30 days at most.
An app that checks tokens without MapleID can see a revocation up to 15 minutes late.
MapleID has no dynamic client registration. Enter the client ID, and the secret of a confidential client, in your MCP client.

Your agent's AI provider receives the credentials that the agent types. MapleID does not control where that provider stores them.

1. Get an agent client

An owner or admin of the organization creates the client on /orgs/<organization id>/developers/apps. See Agent clients. Keep the client ID. A confidential client also has a secret, which MapleID shows one time.

2. Open the authorize URL

Make a PKCE verifier and its S256 challenge. Then open this URL in a browser, or in the browser tool of the agent:

https://mapleid.ca/oauth/v2/authorize?response_type=code
  &client_id=<client id>
  &redirect_uri=<a redirect URI of the client>
  &scope=openid%20offline_access%20mapleid.agent.mcp
  &code_challenge=<challenge>&code_challenge_method=S256
  &state=<random value>

Add prompt=create for a person with no MapleID account.

The person, or the agent with the person's credentials, completes the pages. The login, register, MFA and email pages say: "An agent may fill this form for a person." The table shows the forms. Its names, ids and autocomplete tokens are a contract: MapleID changes them only with notice on this page and on the changelog.

Page	Form	Inputs	Submit
`/login`	`#login-form`	`email` (`#email`, username), `password` (`#password`, current-password)	`#login-submit`
`/register`	`#register-form`	`email` (`#email`, username), `password` (`#password`, new-password), `first_name` (`#first_name`, given-name), `last_name` (`#last_name`, family-name), `phone` (`#phone`, tel), `address_line1` (`#address_line1`, address-line1), `address_line2` (`#address_line2`, address-line2, optional), `city` (`#city`, address-level2), `region` (`#region`, address-level1), `postal_code` (`#postal_code`, postal-code), `country` (`#country`, country), `tenant=organization` (`#tenant-organization`), `tenant=individual` (`#tenant-individual`), `organization_name` (`#organization_name`, organization), `accept_terms=yes` (`#accept_terms`), `agree_promotions=yes` (`#agree_promotions`, optional), `agree_to_tracking_across_third_party_apps_and_services=yes` (`#agree_to_tracking_across_third_party_apps_and_services`, optional). The page has no tenant and organization_name inputs when the person registers with the email of an invitation.	`#register-submit`
`/mfa`	`#mfa-form`	`code` (`#code`, one-time-code)	`#mfa-submit`
`/mfa`	`#mfa-recovery-form`	`recovery_code` (`#recovery_code`, off). Use this form in place of the code form when the person has no authenticator.	`#mfa-recovery-submit`
`/forgot-password`	`#forgot-password-form`	`email` (`#email`, username). The page shows the same notice for an address with an account and for an address with no account.	`#forgot-password-submit`
`/reset-password`	`#reset-password-form`	`password` (`#password`, new-password). The token comes from the link in the reset email. The form sends it back in a hidden token input.	`#reset-password-submit`
`/verify-email`	`#verify-email-form`	`code` (`#code`, one-time-code)	`#verify-email-submit` `action=verify`, or `#verify-email-resend` `action=resend`
`/consent`	`#consent-form`	none	`#consent-allow` `decision=allow`, or `#consent-deny` `decision=deny`
`/logout`	`#logout-form`	none. MapleID shows this page when it cannot prove that the app of the person sent the sign-out request.	`#logout-submit`
`/invite/<token>`	`#invite-accept-form`	none. The page has this form only for a person who has a MapleID session. For other people, it has links to sign in and to register.	`#invite-accept-submit`
`/reauth`	`#reauth-form`	`password` (`#password`, current-password), `code` (`#code`, one-time-code). MapleID shows this page before a change that needs a recent sign-in. The page has the code input only when the person has two-step verification on.	`#reauth-submit`
`/account/close`	`#close-account-form`	`confirm=yes` (`#confirm`). The form also sends the id of each organization that the close deletes, in hidden org inputs. Closing the account cannot be undone.	`#close-account-submit`

Each form also has a hidden csrf_token field. Send it back with the same cookies.

4. Get the tokens

Send the code to https://mapleid.ca/oauth/v2/token with grant_type=authorization_code, the code, the redirect URI, the client ID and the PKCE verifier. A confidential client also sends HTTP Basic authentication with its secret.

5. Call the API

GET https://mapleid.ca/v1/agent/organization
Authorization: Bearer <access token>

The answer names the organization of the client and the role of the person. The reference lists every operation and tool. When the access token expires, use the refresh token at the token endpoint.