Authenticate with Gatekeeper

Bespot is based on OAuth 2.0 Client Credentials Flow, as defined in RFC 6749, section 4.4, for authenticating clients and authorise them to access protected resources. This page is organised to depict this flow, describe the related components and, finally, provide instructions for a client on how to achieve that.

Components

Client

The client can be Bespot’s SDKs that request access to resources or any 3rd party server that needs to be authenticated and communicate securely with the system. The client needs to provide valid credentials, acquire an access token and, finally, use it for accessing protected resources.

Gatekeeper Auth

Bespot’s Gatekeeper Auth server is responsible for authenticating clients. To achieve that, it is based on the Client Credentials Flow. More specifically, a client id and a client secret need to be provided as input. Then, if the credentials provided are valid, the authentication is successful and an access token is returned. The access token is in the form of JWT based on RFC 7519. Finally, this access token is used to retrieve resources from the Gatekeeper API (see next section). The access token is only valid for a predefined period. If the access token expires, the client needs to start over with the authentication process and acquire a new one.

Gatekeeper API

Bespot’s Gatekeeper API is a collection of protected resources. To consume any Gatekeeper API resource, the Authorization HTTP header is required. Firstly, each client needs to be authenticated with the Gatekeeper Auth server providing the authentication credentials and acquiring a valid access token. Then, this access token should be used in each subsequent API HTTP request for the client to be authorised to access the resources. The Authorization HTTP header should be filled with the acquired JWT access token prefixed with the following string: Bearer .

Example: Authorization: Bearer JWT_ACCESS_TOKEN

Database

Bespot’s database is responsible for keeping short-lived access tokens.

Usage

See below the details of the authentication request to acquire the JWT access token.

Resource [POST]

[/api/auth]

Request

{
    "client-id": "CLIENT-ID",
    "client-secret": "CLIENT-SECRET",
}

Response

{
    "access": "TOKEN"
}

Example cURL

curl --location 'https://antifraud.bespot.dev/api/auth' \
--header 'Content-Type: application/json' \
--data '{ "client-id": "CLIENT_ID", "client-secret": "CLIENT_SECRET" }'

Authorization

Bespot uses API Keys to authorize different types of clients to access different types of resources.

The acquired API Key should be provided in each Gatekeeper API request to allow access to resources corresponding to specific client types.

Usage

Each client connected to Gatekeeper API should provide the acquired API Key as an HTTP Header on each request.

Example: x-api-key: X-API-KEY