Authorization reference

RocketVerifier Connect follows OAuth 2.0 (RFC 6749) with PKCE (RFC 7636). This page lists every endpoint, parameter and error.

Endpoints

Identifiers and lifetimes

Treat all tokens as opaque strings. Do not parse them; the format after the prefix can change.

GET /oauth/authorize

Redirect the user's browser here. RocketVerifier signs them in, shows the consent screen, then redirects to your redirect_uri.

Consent screen

• The user picks the account to connect: their personal account or an organization where they are owner or admin.
• Each scope is shown in plain language. The user can set an optional monthly credit cap for your app.
• Apps that have not passed review show an Unverified app badge.
• Verified apps skip the screen when the user already granted every requested scope. Unverified apps always show it. Ask for new scopes and the screen lists only what changed.

Success redirect

https://yourapp.com/callback?code=CODE_FROM_REDIRECT&state=3f9c2a8e

Error redirect

https://yourapp.com/callback?error=access_denied&error_description=The+user+cancelled&state=3f9c2a8e

POST /api/oauth/token

Form-encoded (application/x-www-form-urlencoded). Returns JSON. Never call it from a browser with a client secret.

Client authentication

grant_type=authorization_code

curl https://app.rocketverifier.com/api/oauth/token \
  -u "rvapp_xxxxxxxxxxxx:rv_cs_xxxxxxxxxxxxxxxx" \
  -d grant_type=authorization_code \
  -d code=CODE_FROM_REDIRECT \
  -d redirect_uri=https://yourapp.com/callback \
  -d code_verifier=VERIFIER

grant_type=refresh_token

Success response

{
  "access_token": "rv_at_xxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rv_rt_xxxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "verify:bulk jobs:read account:read"
}

scope is what the user approved, which can be fewer scopes than you asked for. Check it before you show features that depend on a scope.

Error response

{
  "error": "invalid_grant",
  "error_description": "The refresh token is invalid, expired or revoked"
}

Refresh token rotation and reuse detection

• Every successful refresh returns a new refresh token and invalidates the one you sent.
• If an already used refresh token is presented again, RocketVerifier assumes it was stolen and revokes the whole grant: every access and refresh token for that user and app stops working. Your app receives a grant.revoked webhook with reason: "refresh_token_reuse".
• Write the new refresh token to storage before you use the new access token, and run only one refresh at a time per connection. See Security best practices.
• A refresh token that is not used for 90 days expires. The user has to connect again.

Calling the API

curl https://api.rocketverifier.com/v1/credits \
  -H "Authorization: Bearer rv_at_xxxxxxxxxxxxxxxxxxxxxxxx"

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"

{
  "error": {
    "code": "invalid_token",
    "message": "The access token is expired or revoked",
    "details": null
  }
}

See Error Codes and Rate Limits for the shared formats.

POST /api/oauth/revoke

RFC 7009. Revoking a refresh token ends the whole grant (the user is disconnected). Revoking an access token ends only that token. Authenticate the same way as the token endpoint. Always returns 200, even for an unknown token.

curl https://app.rocketverifier.com/api/oauth/revoke \
  -u "rvapp_xxxxxxxxxxxx:rv_cs_xxxxxxxxxxxxxxxx" \
  -d token=rv_rt_xxxxxxxxxxxxxxxxxxxxxxxx \
  -d token_type_hint=refresh_token

POST /api/oauth/introspect

RFC 7662. Your app can introspect only tokens issued to it; anything else returns {"active": false}. Client authentication is required.

curl https://app.rocketverifier.com/api/oauth/introspect \
  -u "rvapp_xxxxxxxxxxxx:rv_cs_xxxxxxxxxxxxxxxx" \
  -d token=rv_at_xxxxxxxxxxxxxxxxxxxxxxxx

{
  "active": true,
  "client_id": "rvapp_xxxxxxxxxxxx",
  "scope": "verify:bulk jobs:read account:read",
  "token_type": "Bearer",
  "exp": 1793534400,
  "iat": 1793530800,
  "iss": "https://app.rocketverifier.com",
  "aud": "https://api.rocketverifier.com"
}

POST /api/oauth/register

RFC 7591 dynamic client registration, for MCP clients and other tools that register themselves. It creates public clients only (token_endpoint_auth_method: none, PKCE required). Redirect URIs must be https or a loopback address (http://127.0.0.1, http://localhost). Apps created this way start unverified. For a confidential server app, create it in the dashboard instead. The full request and response are on the MCP connector page.

Server metadata

Discover every value above from https://app.rocketverifier.com/.well-known/oauth-authorization-server (RFC 8414). Libraries that support discovery need only the issuer.

{
  "issuer": "https://app.rocketverifier.com",
  "authorization_endpoint": "https://app.rocketverifier.com/oauth/authorize",
  "token_endpoint": "https://app.rocketverifier.com/api/oauth/token",
  "revocation_endpoint": "https://app.rocketverifier.com/api/oauth/revoke",
  "introspection_endpoint": "https://app.rocketverifier.com/api/oauth/introspect",
  "registration_endpoint": "https://app.rocketverifier.com/api/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
  "revocation_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
  "introspection_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
  "scopes_supported": [
    "verify:single", "verify:bulk", "jobs:read", "jobs:write", "webhooks:manage",
    "credits:read", "monitors:read", "monitors:write", "account:read"
  ],
  "service_documentation": "https://docs.rocketverifier.com/oauth"
}

grant.revoked webhook

Sent to the webhook URL set on your app whenever a connection ends. Delete the stored tokens for that grant and show the Connect button again.

{
  "event": "grant.revoked",
  "event_id": "evt_xxxxxxxxxxxx",
  "timestamp": "2026-11-01T12:00:00Z",
  "data": {
    "grant_id": "4f1d9c2e-...",
    "client_id": "rvapp_xxxxxxxxxxxx",
    "user_email": "jane@acme.com",
    "account_type": "personal",
    "organization_id": null,
    "reason": "user_disconnected"
  }
}

Signed with X-RocketVerifier-Signature using your app's webhook secret, the same scheme as every other RocketVerifier webhook. See Verifying Signatures.

More in Build an App