Skip to main content
API docs by Redocly

Access Control (0.0.9)

Download OpenAPI specification:Download

The Access Control API provides a comprehensive set of endpoints designed to manage authentication and authorization, specifically focusing on OAuth 2.0 standards. By utilizing this API, developers can seamlessly integrate secure access control mechanisms into their applications and services, ensuring adherence to industry best practices.

This API documentation outlines the supported OAuth 2.0 endpoints, detailing the required input parameters, expected response structures, and applicable error messages. This enables developers to effectively manage user authentication, resource access, and permissions within their applications.

Oauth

Authorization Endpoint

This endpoint is the starting point for the OAuth 2.0 Authorization Code flow, a secure method for obtaining access tokens. When a client application wants to access a user's protected resources, it directs the user's browser to this authorization endpoint.

Upon accessing this endpoint:

  1. The user will be prompted to log in if they haven't already. This ensures that the user is aware of and in control of the permissions they grant.
  2. After successful authentication, the user will be presented with a consent screen. This screen will detail the permissions the client application is requesting.
  3. If the user grants the requested permissions, the authorization server will redirect the user's browser back to the client application using the provided redirect_uri.
  4. Appended to this redirect will be an important piece of information: the authorization code. This short-lived code is essential for the next step in the flow, where the client application exchanges it for an access token.

It's worth noting that this flow provides an added layer of security. The user's credentials are never shared directly with the client application. Instead, the application receives an authorization code, which can only be used in conjunction with the application's own credentials to obtain an access token.

Authorizations:
ApplicationToken
query Parameters
response_type
required
string
Example: response_type=code

The response type requested by the client. Must be set to "code" for the authorization code flow.

client_id
required
string

The client identifier, which is the Marpp ID.

redirect_uri
required
string
Example: redirect_uri=https://example.com/callback

The redirect URI to which the authorization response will be sent.

scope
string

The requested scope(s) for the access token. Multiple scopes can be specified using space-separated values.

state
string

An opaque value used by the client to maintain state between the request and the callback. The authorization server includes this value when redirecting the user back to the client.

code_challenge
string

The code challenge derived from the code verifier. Required for PKCE (Proof Key for Code Exchange) in the authorization code flow.

code_challenge_method
string
Example: code_challenge_method=S256

The method used to derive the code challenge. Required for PKCE (Proof Key for Code Exchange) in the authorization code flow.

Responses

Request samples 

curl --request GET \
  --url 'https://api-marco.finboot.com/v1/auth/authorize?response_type=code&client_id=SOME_STRING_VALUE&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=SOME_STRING_VALUE&state=SOME_STRING_VALUE&code_challenge=SOME_STRING_VALUE&code_challenge_method=S256' \
  --header 'ApplicationToken: REPLACE_KEY_VALUE'

JWKs Endpoint

The JWKs (JSON Web Key Set) endpoint provides a set of public keys used by the authorization server. These keys are essential for clients and other entities to verify the digital signatures of tokens issued by the server.

By accessing this endpoint, client applications can retrieve the current public keys and use them to validate the JWT (JSON Web Token) signatures, ensuring the tokens' authenticity and integrity. This dynamic retrieval ensures that clients can adapt to key rotations and other security measures implemented by the authorization server.

The returned JWKS is in a standard format, making it compatible with many JWT libraries and tools.

Authorizations:
ApplicationToken

Responses

Request samples 

curl --request GET \
  --url https://api-marco.finboot.com/v1/auth/certs \
  --header 'ApplicationToken: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

Obtain an access token

Use this endpoint to obtain an access token. The required parameters vary based on the grant type:

Authorization Code Grant with PKCE:

  • grant_type: Must be set to authorization_code.
  • code: The authorization code received from the authorization server.
  • redirect_uri: The same redirect URI that was used to obtain the authorization code.
  • client_id: The Marpp ID.
  • code_verifier: The original code verifier used to generate the code challenge.

Client Credentials Grant using Service Account:

  • grant_type: Must be set to client_credentials.
  • service_account: The identifier of the service account.
  • client_id: The Marpp ID.
  • client_secret: The service account's apiKey.

Client Credentials with JWT Bearer Token:

  • grant_type: Must be set to client_credentials.
  • client_assertion_type: Must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
  • client_assertion: The JWT Bearer token.
  • client_id: The Marpp ID.
Request Body schema: application/x-www-form-urlencoded
client_assertion
string

The JWT Bearer token (required for JWT Bearer token).

client_assertion_type
string

Assertion type (required for JWT Bearer token).

client_id
string

The Marpp ID for the Application requesting the token.

client_secret
string

The secret used for requesting a token (not required if using JWT Bearer token).

code
string

The authorization code (required for authorization_code grant type).

code_verifier
string

The original code verifier used for PKCE in the authorization_code grant type.

grant_type
string

The type of grant being used.

redirect_uri
string

The redirect URI (required for authorization_code grant type).

service_account
string

The identifier of the service account being used to authenticate the client.

Responses

Request samples

Content type
application/x-www-form-urlencoded
Example
client_id=Marpp12345&code=ABC123&code_verifier=XYZ789&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "expires_in": 3600,
  • "token_type": "Bearer"
}

Authentication

User Login Endpoint

This endpoint facilitates user authentication. Clients send user credentials (username and password) to this endpoint to establish an authenticated session. Upon successful authentication, the server sets an HTTP-only cookie named FINBOOTSESSIONID. This cookie represents the authenticated session and allows for immediate redirections without the need for re-authentication.

Authorizations:
ApplicationToken
Request Body schema: application/json

A JSON object containing the user's username and password.

password
required
string

The user's password.

username
required
string

The email for the user.

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "username": "string"
}

User Logout Endpoint

This endpoint allows authenticated users to log out, effectively ending their session. When a user logs out, the associated FINBOOTSESSIONID cookie is invalidated on the server side, ensuring it can't be used for further authenticated requests.

Clients should call this endpoint when users explicitly choose to log out or when refreshing authentication tokens to ensure a clean session state.

Authorizations:
ApplicationToken

Responses

Request samples 

curl --request POST \
  --url https://api-marco.finboot.com/v1/auth/logout \
  --header 'ApplicationToken: REPLACE_KEY_VALUE'

Identities Init

Init new user

Initializes the identity after they have been sent the onboarding email

Authorizations:
ApplicationToken
Request Body schema: application/json
acceptTnC
boolean

Indicates whether the user accepts the Terms and Conditions.

UserDetails (object)

Additional user details specific to the identity type.

initToken
string

The initialization token required to set up the identity.

Responses

Request samples

Content type
application/json
{
  • "acceptTnC": true,
  • "additional": {
    },
  • "initToken": "string"
}

Response samples

Content type
application/json
{
  • "email": "string"
}