Endpoints, scopes and errors
OAuth endpoints return JSON directly. They do not use the public API's success / data envelope or accept an API key in place of OAuth credentials. Use your connection's endpoint URLs for the relevant environment.
Endpoint reference
| Endpoint | Method | Authentication | Purpose |
|---|---|---|---|
/api/v1/oauth/authorize | GET | Member signs in through RemyPass | Start authorisation in the browser |
/api/v1/oauth/token | POST | Client ID and secret | Exchange a code with its PKCE verifier |
/api/v1/oauth/userinfo | GET | Bearer access token | Retrieve identity and current eligibility |
/api/v1/oauth/revoke | POST | Client ID and secret | Revoke an access token |
The production host is https://api.remypass.com. Token and revocation requests support form-encoded bodies. Use either HTTP Basic (client_secret_basic) or body credentials (client_secret_post), never both. For Basic authentication, form-encode the client ID and secret individually before joining them with a colon and Base64-encoding the result; RemyPass-generated credentials use URL-safe characters.
Authorisation parameters and token exchange examples are in the flow guide.
Member profile
GET /api/v1/oauth/userinfo
Authorization: Bearer <access_token>
Example response with all scopes:
{
"sub": "507f1f77bcf86cd799439011",
"id": "507f1f77bcf86cd799439011",
"company_id": "507f191e810c19729de860ea",
"name": "Alex Member",
"given_name": "Alex",
"family_name": "Member",
"member_id": "MEM001",
"email": "alex@example.com",
"membership_active": true,
"membership_type_ids": ["507f1f77bcf86cd799439012"]
}
sub, its alias id, and company_id are always returned. profile adds the name fields and display member number; email adds the email address; membership adds active membership status and membership type IDs. Membership data is evaluated at request time. Access is also checked at approval and code exchange.
Use sub as the stable external account identifier, scoped to this provider/organisation. Do not use member_id or email as the permanent identity key: these can change. No email_verified claim is provided. An email match alone is not proof that the person owns an existing account in your application.
Scope summary
| Scope | Additional fields |
|---|---|
profile | name, given_name, family_name, member_id |
email | email |
membership | membership_active, membership_type_ids |
sub, id and company_id are returned for every valid token. Omitting scope requests all three supported scopes. An empty scope, an unrecognised scope or openid is rejected. Scope names are case-sensitive.
Membership eligibility is enforced independently of the requested scopes. Omitting the membership scope does not bypass a connection's active-membership requirement.
Lifetimes and revocation
| Item | Lifetime |
|---|---|
| Pending authorisation request | 10 minutes |
| Authorisation code | 60 seconds, one exchange |
| Access token | 10 minutes, potentially revoked earlier |
Tokens are opaque, not JWTs. There is no refresh-token endpoint or grant. Reauthorise after token expiry. Portal logout, session revocation, member deactivation, connection changes or loss of required membership eligibility can invalidate access earlier.
To revoke a token, POST token=<access_token> to /api/v1/oauth/revoke using client authentication. An unknown token returns HTTP 200 with an empty body, as does successful revocation. A connection can revoke only its own tokens.
A valid OAuth token does not determine how long your application's own session should last. See session and membership behaviour.
Errors
{
"error": "invalid_grant",
"error_description": "Invalid PKCE verifier"
}
| Error | What to check |
|---|---|
invalid_request | Required parameters, registered callback and parameter types |
invalid_client | Client ID, secret, enabled state and use of one authentication method |
unsupported_response_type | Use response_type=code |
unsupported_grant_type | Use grant_type=authorization_code |
invalid_scope | Request only profile, email and membership |
invalid_grant | Code expiry/reuse, correct client, exact callback URL and original verifier |
access_denied | Member cancellation, inactive account, disabled portal or missing eligible membership |
invalid_token | Expired/revoked token or access no longer valid at user-info time |
temporarily_unavailable | Rate limit exceeded; wait before retrying |
server_error | Request could not be completed; retry with a new login flow where needed |
Client authentication failures return HTTP 401. User-info failures caused by invalid tokens or lost access also return HTTP 401, with a Bearer WWW-Authenticate header. Eligibility failures during token exchange can return HTTP 403. Other invalid token-exchange inputs generally return HTTP 400.
Authorisation errors redirect to the registered callback only when the client and exact callback can be validated. A valid supplied state is returned with that error. Invalid client or callback details return a local JSON error. Always check callback state before processing either success or error responses.
OAuth public endpoints share a limit of 60 requests per minute per IP within each API process, in addition to general API limits. A rate-limited request returns HTTP 429. Responses use Cache-Control: no-store and Pragma: no-cache.