Every endpoint of the public API that your end users reach on your brand domain, with the credential each one needs.
The public API serves your end users: sign-in and sign-up, their organizations and members, your plans, checkout and subscriptions, invoices and usage. The hosted pages, the customer portal and the React components call it, and so can your own pages. This page is an index of the endpoints; request and response bodies are not described here yet.
Common conventions
Where it is served. On your verified brand domain, under /rest: for the brand domain account.example.com, each path below is preceded by https://account.example.com/rest. The region picks your application from the host name of the request, so every call must arrive with your brand domain as its Host; from a browser, forward a path on your own origin as described in The React components.
Credentials. The Credential column names what an endpoint needs in Authorization: Bearer <token>:
Credential
What it is
End-user session
The access token of a signed-in end user, issued by POST /public/v1/auth/login, POST /public/v1/auth/register or POST /public/v1/auth/verification/confirm, and renewed with POST /public/v1/auth/refresh. The session belongs to one organization of your customer; POST /public/v1/auth/switch changes it
None
No bearer token. The endpoint relies on something else: credentials, a refresh token or a one-time token in the request body, or the request's host
Changing billing, members and invitations needs the end user to be an owner or admin of their organization. Paths with {orgId} must name the session's organization. Your backend checks the same session tokens with the Server SDK.
Requests and answers. Bodies are JSON. Unknown fields in a request body are dropped. An error answers with the body described in Error codes, with a stable code.
Lists. The Query column names the query parameters an endpoint takes. Lists that page take limit together with either page or cursor.
Endpoints
Sign-in and session
Method
Path
Credential
Query
Purpose
POST
/public/v1/auth/oauth/{provider}/authorization
None
Get the provider authorization URL to start a social sign-in with PKCE
POST
/public/v1/auth/oauth/{provider}/token
None
Exchange a social sign-in authorization code for an end-user session
POST
/public/v1/auth/register
None
Register an end-user account with a new organization or by invitation
POST
/public/v1/auth/login
None
Sign an end user in with email and password and obtain a session
GET
/public/v1/auth/me
End-user session
Read the signed-in end user profile, memberships and current context
PATCH
/public/v1/auth/me
End-user session
Update the profile of the signed-in end user, such as display name
PUT
/public/v1/auth/me/avatar
End-user session
Upload a profile picture for the signed-in end user; anyone with the picture's URL can view it
DELETE
/public/v1/auth/me/avatar
End-user session
Remove the profile picture of the signed-in end user
POST
/public/v1/auth/logout
End-user session
Sign the end user out of the current session
POST
/public/v1/auth/change-password
End-user session
Change the password of the signed-in end user
POST
/public/v1/auth/verify-email
None
Verify an email address using a token from an older verification link
POST
/public/v1/auth/password-reset/request
None
Request a password reset link to be emailed to an end user
POST
/public/v1/auth/password-reset/confirm
None
Set a new end-user password using a password reset token
POST
/public/v1/auth/resend-verification
End-user session
Resend an email verification link to the signed-in end user
POST
/public/v1/auth/verification/confirm
None
Confirm an email verification code and sign the end user in
POST
/public/v1/auth/verification/resend
None
Send a new email verification code for an unverified account
POST
/public/v1/auth/verification/email
None
Change the email of an unverified account and send a new code
POST
/public/v1/auth/refresh
None
Obtain a fresh end-user access token using a refresh token
POST
/public/v1/auth/switch
End-user session
Switch the end-user session to another organization or application
Sign-in gate
Method
Path
Credential
Query
Purpose
GET
/public/v1/identity/resolve
None
projectId
Resolve the identity gate, branding and enabled social providers for this host
Organizations and members
Method
Path
Credential
Query
Purpose
GET
/public/v1/organizations
End-user session
List the organizations the signed-in end user belongs to
GET
/public/v1/organizations/{orgId}
End-user session
Read the details of the end user active organization
PATCH
/public/v1/organizations/{orgId}
End-user session
Rename the organization that is active in the end user session
GET
/public/v1/organizations/{orgId}/members
End-user session
List the members of the end user active organization