The flow
An authorization code flow. Send the person to TAP with your client ID, the redirect URI and the scopes you ask for. They sign in, see the consent screen, and come back with a code. Exchange it for tokens. Access tokens last a day, refresh tokens 30 days.
A person needs a verified phone number to reach the consent screen. TAP asks for it and sends them back.
The scopes
| Scope | What the person reads |
|---|---|
| profile | Read your name, email address and passport |
| artists:read | Read public artists and the artists you belong to |
| artists:connect | Connect the artists you own to this app |
profile is the default.
What each scope opens
- profile: GET /api/v1/me, the person and, once issued, their passport.
- artists:read: GET /api/v1/artists and GET /api/v1/artists/{identifier}. An approved app also gets it on a server-to-server token, with no person present.
- artists:connect: POST /api/v1/me/connections. Only an app token carries it, never a personal token.
What the app may do after that
A scope is what the person approves. What your app may then do to an artist is a capability, and TAP grants those, one at a time, to the app itself. There are four: provision an artist, publish it and take it offline, hand a person temporary edit access, and hand out access keys to the EPK. A capability is exercised on your own server-to-server token, never on the token a person granted you, so consent alone opens none of them. Ask TAP for the ones your app needs: Register an app.
Who the person is
GET /api/v1/me
needs the profile scope and returns their id, name, email, and whether the email is verified. A person who holds a passport gets a passport object with it: their photo, the date it was issued, and the artists they belong to. Their name is the name at the top level. Each artist carries its handle and name; role, what the person does there; permission, either owner or member, which is what they may change; and verified_at, the date TAP verified the artist, or null. Without an issued passport the object is null. What the holder sees on their side: Apps and your passport.
Revocation
The person can revoke the app under Account, on the Sign in with TAP tab. Tokens stop working at once. Design for it.
Before approval
Until we approve the app, a person who tries to sign in sees that the app has not cleared review and that nothing was shared with it.