OAuth authorization
API Documentation / Authorization
Finovio's proposed public authorization contract follows OAuth 2.1 Authorization Code with PKCE. Applications are confidential clients and must perform token exchanges from a trusted server.
Why the client secret is required
The client secret authenticates the registered application when it exchanges or refreshes tokens. This is the standard authorization-code pattern for web-server applications that can keep credentials private.
The secret is not included in the browser redirect to /oauth/authorize, sent to an end user, or attached to accounting API requests. It is sent only from the application's trusted server to /oauth/token using HTTP Basic authentication over TLS.
PKCE solves a different problem. Its one-time verifier binds the callback code to the authorization attempt, while the client secret identifies the application. Requiring both provides protection if an authorization code is intercepted and protection against another client impersonating the application.
Authorization request
Send users to GET /oauth/authorize with these query parameters:
| Parameter | Required | Contract |
|---|---|---|
response_type |
Yes | Must be code. |
client_id |
Yes | The active client ID issued to the application. |
redirect_uri |
Yes | Must exactly match a registered redirect URI. |
scope |
Yes | Space-delimited scopes requested for this grant. |
state |
Yes | An unguessable value used to prevent request forgery. |
code_challenge |
Yes | Base64url-encoded SHA-256 digest of the verifier. |
code_challenge_method |
Yes | Must be S256. |
The authorization screen lets the user choose one tenancy and one subsidiary. It may reduce the requested scope set, but cannot expand it.
Authorization response
Approval redirects to the registered URI with code and the original state. The code is short-lived, single use, and bound to the client, redirect URI, and PKCE challenge.
Denial or another authorization failure redirects with standard OAuth parameters:
https://app.example.com/oauth/callback?error=access_denied&error_description=The%20request%20was%20not%20approved&state={state}
Token exchange
Exchange the code at POST /oauth/token using application/x-www-form-urlencoded. Confidential clients authenticate with HTTP Basic authentication. The request must contain grant_type=authorization_code, code, redirect_uri, and code_verifier.
The Basic username is the client ID and the password is the raw client secret issued by Finovio. Do not send the stored hash, place either value in the form body, or expose the resulting Authorization header to frontend code.
The response contains an opaque bearer access token and refresh token. Never inspect or depend on the token's internal format.
Refresh tokens
Request a new token pair before the access token expires:
POST /oauth/token HTTP/1.1
Host: api.finov.io
Authorization: Basic {base64_client_id_and_secret}
Content-Type: application/x-www-form-urlencoded
Accept: application/json
grant_type=refresh_token&refresh_token={refresh_token}
Refresh tokens rotate. A successful refresh invalidates the token used in the request and returns a replacement. Store the replacement atomically. Reuse of an invalidated refresh token may revoke the grant's active token family.
Revocation
A token stops working when it expires, the user revokes the subsidiary grant, the application rotates its credentials, or Finovio revokes or deletes the application. Clients must handle 401 Unauthorized by stopping the request and beginning authorization again when refresh cannot recover the session.
Client credential rotation revokes the previous credential. Existing tokens issued under that credential may also be revoked and must not be assumed to remain valid.