The Marketplace API is in a private beta. It answers only for accounts Investorlift has enabled. Access says how to ask for one. A route shape on these pages can change before the beta ends. The changelog records every change.
Authorization header as Bearer. The token names
the person, your application and the scopes. The API reads the permission of that person from its database on every
request. The God Mode API is different: it takes a zpka_ key (Authentication), and
a key never opens a marketplace route.
The issuer
The issuer ishttps://mogul.investorlift.com/api/auth. Read its endpoints from the discovery document. Do not type
them.
The flow
1
Register a client
Register your application once at
/oauth2/register, or ask Investorlift for a registered app (Access).
A dynamically registered client is personal. It holds consent from at most one organization and three users. The fourth
consent answers client_limit on the consent page. A registered app connects many organizations. It shows its name and a
verified badge on the consent page.2
Send the person to the authorization endpoint
Use the authorization code grant with PKCE, method
S256. Ask for the scopes you need and for offline_access. The
consent page prints one sentence per scope and the name of your application. A dynamically registered client shows as
“Unregistered application” with its redirect host.The page also carries the Marketplace API Terms checkbox. A seller accepts the terms once for the organization. A buyer
accepts them once as a person.3
Exchange the code for tokens
Send the code, the PKCE verifier and
resource=https://api.investorlift.com/marketplace/v1 to the token endpoint. The
resource value puts the API in the audience of the access token. Without it, the token has no marketplace audience,
and the gateway answers 401 unauthorized. The answer carries an access token and a refresh token.4
Call the API
Send
Authorization: Bearer <token> on every request. Start with GET /me, which says what the token can do.5
Refresh
A marketplace access token lives 15 minutes. Use the refresh token to get a new pair before it expires. Refresh tokens
rotate: every refresh answers a new refresh token, and the old one stops. A refresh token lives 30 days.
Revoke a token
Send the refresh token to/oauth2/revoke under the issuer. The revocation ends the refresh token and every access
token it minted. A person can also remove your application in their account settings on Mogul. The old access token then
answers 401 unauthorized within 15 minutes, and a refresh fails at once.
The 14 scopes
Read, write and manage are separate grants. A CRM that only reads events never holds a write scope. Ask for the smallest set that does the job. The consent page prints the sentence in the second column.marketplace:profile opens GET /me, which both sides call. A token without the scope of an operation answers
403 insufficient_scope, and the body names the scope in scope. The three proof of funds routes under
/buy/me/proof-of-funds are under offers:write.
The two sides and GET /me
Every route lives under one side. A /sell/ route acts for your own organization, limited by your role. A /buy/ route
acts for you as a buyer. One token can hold both sides. GET /me is the one route outside both. Call it first: it
answers what the token can do now.
GET /me answers one object in data:
Roles
An organization has owners, admins and members. Every write scope acts for any member. Two scopes reach personal data and delivery endpoints:contacts:read and webhooks:manage. The role gate sits on the operation, not on the token.
A member’s token on a seller-side webhook route answers 403 insufficient_role. The body names the roles that run the
operation in required_roles, and your role in role. The six seller-side webhook operations carry the gate, and no
other operation does. The API serves a buyer’s email, phone and phone type only when the token holds contacts:read
and the member is an owner or an admin. Otherwise those fields are absent, and the rest of the response is normal.
The API reads the role from the membership on every request, never from the token. When a membership ends, the token
stops for that organization on its next request.
What the gateway checks and what the origin loads
The gateway atapi.investorlift.com verifies the access token against the keys of the issuer: the signature, iss,
exp and aud. It then forwards the request to the origin with the identity from the token. The origin reads the
person from X-On-Behalf-Of as user:<sub>, your client id, the scopes and the request id from headers the gateway
sets. The gateway deletes your token before the request leaves it, and it drops any of these headers you send. You
never send them.
A claim is identity, never permission. On every request the origin loads the user, the own organization, the role, the
designations and the standing from its database. So a ban, a role change or a stop takes effect on the next request,
inside the 15 minutes of the token. A suspended or deleted account answers 401 unauthorized. So does an account with
no verified email address. A stopped client, user or organization answers 403 forbidden.
Call GET /me
The first call of every integration. Put the access token in the environment variable MARKETPLACE_TOKEN.