Authentication

API endpoints

User tokens

Create a new user and generate an associated access token

POST https://{domain}.biapi.pro/2.0/auth/init

This endpoint generates a new access token related to a new user.

Request body: AuthTokenInitRequest object

Response body: AuthToken object

Generate a temporary code

GET https://{domain}.biapi.pro/2.0/auth/token/code

This endpoint generates a new temporary code for the current user.

This endpoint requires header authentication with a valid user access token.

In case the access token is already used by a trusted device, and you want to temporarily let another one (for example a web browser) access user resources, use this endpoint to generate a code that will expire in 30 minutes. If the generated code is intended to be used with our webview, you can use the singleAccess token type.

Query Parameters

Name	Type	Description
type	String	Type of the temporary code.

Name

Type

Description

type

String

Type of the temporary code.

Response body: AuthCode object

Exchange a temporary code for a permanent user access token

POST https://{domain}.biapi.pro/2.0/auth/token/access

This endpoint uses a temporary code to generate a permanent user access token.

Request body: AuthTokenExchangeRequest object

Response body: AuthTokenExchange object

Revoke an access token

DELETE https://{domain}.biapi.pro/2.0/auth/token

This endpoint invalidates permanent access tokens. Subsequent calls using the provided permanent access token will fail.

The invalidated token is the one that is provided in the header for authentication.

Generate a new token for an existing user

POST https://{domain}.biapi.pro/2.0/auth/renew

This endpoint generates a new permanent access token for an existing user, and revokes former tokens if explicitly requested.

Request body: AuthRenewRequest object

Response body: AuthTokenExchange object

Create a new user and generate an associated access token

POST https://{domain}.biapi.pro/2.0/auth/init

Generate a temporary code

GET https://{domain}.biapi.pro/2.0/auth/token/code

Query Parameters

Name	Type	Description
type	String	tWTP6Ewv25HX

Name

Type

Description

type

String

tWTP6Ewv25HX

Exchange a temporary code for a permanent user access token

POST https://{domain}.biapi.pro/2.0/auth/token/access

Revoke an access token

DELETE https://{domain}.biapi.pro/2.0/auth/token

Generate a new token for an existing user

POST https://{domain}.biapi.pro/2.0/auth/renew

Service tokens

Generate a service token

POST https://{domain}.biapi.pro/2.0/auth/token

This endpoint generates a special access token with a dedicated service scope. The generated token will expire after 30 minutes.

A service token is a token that is not associated with a user but rather used to access a specific feature or service. For example, the Pay product requires the use of a payment token.

Request body: AuthServiceTokenRequest object

Response body: AuthServiceToken object

Generate a service token

POST https://{domain}.biapi.pro/2.0/auth/token

Data model

AuthTokenInitRequest object

Property Type Required Description

Property	Type	Required	Description
`client_id`	String	No	The ID of the calling client application.
`client_secret`	String	No	The client secret associated with the client ID.

client_id

String

The ID of the calling client application.

client_secret

String

The client secret associated with the client ID.

If your client application credentials (client_id and client_secret) are both supplied, the generated token will be permanent. Otherwise, the token will expire in 30 minutes.

By default, the created user is temporary and will be deleted after 30 minutes if no permanent token is generated during this timeframe.

AuthToken object

Property Type Description

Property	Type	Description
`auth_token`	String	An access token to use for subsequent API calls.
`type`	String	The type of the token, `temporary` or `permanent` .
`id_user`	Integer	ID of the created user.
`expires_in`	Integer or null	The optional expiration delay of the token, in seconds.

auth_token

String

An access token to use for subsequent API calls.

type

String

The type of the token, temporary or permanent .

id_user

Integer

ID of the created user.

expires_in

Integer or null

The optional expiration delay of the token, in seconds.

AuthTokenType value

Value Description

Value	Description
`singleAccess`	The code can only be used once.
`requestAccess`	The code expires after 30 min.

singleAccess

The code can only be used once.

requestAccess

The code expires after 30 min.

AuthCode object

Property Type Description

Property	Type	Description
`code`	String	The generated temporary code.
`type`	String	The type of the generated code. The only value is `temporary`.
`access`	String	The type of access granted, `single` or `standard`.
`expires_in`	Integer or null	The expiration delay of the code, in seconds.

code

String

The generated temporary code.

type

String

The type of the generated code. The only value is temporary.

access

String

The type of access granted, single or standard.

expires_in

Integer or null

The expiration delay of the code, in seconds.

AuthTokenExchangeRequest object

Name Type Required Description

Name	Type	Required	Description
`grant_type`	String	No	The only accepted (and default) value is `authorization_code`.
`client_id`	String	Yes	The ID of the calling client application.
`client_secret`	String	Yes	The client secret associated with the client ID.
`code`	String	Yes	The temporary code that was delivered.

grant_type

String

The only accepted (and default) value is authorization_code.

client_id

String

Yes

The ID of the calling client application.

client_secret

String

Yes

The client secret associated with the client ID.

code

String

Yes

The temporary code that was delivered.

AuthTokenExchange object

Property Type Description

Property	Type	Description
`access_token`	String	The generated permanent user access token.
`token_type`	String	The type of token. The only value is `Bearer`.

access_token

String

The generated permanent user access token.

token_type

String

The type of token. The only value is Bearer.

AuthServiceTokenRequest object

Name Type Required Description

Name	Type	Required	Description
`grant_type`	String	Yes	The only accepted value is `client_credentials`.
`client_id`	String	Yes	The ID of the calling client application.
`client_secret`	String	Yes	The client secret associated to the client ID.
`scope`	AuthScope string or array	Yes	The permission scopes to authorize for this token. It can be a simple string value, or an array for multiple scopes.

grant_type

String

Yes

The only accepted value is client_credentials.

client_id

String

Yes

The ID of the calling client application.

client_secret

String

Yes

The client secret associated to the client ID.

scope

AuthScope string or array

Yes

The permission scopes to authorize for this token. It can be a simple string value, or an array for multiple scopes.

AuthScope values

Product Name Description

Product	Name	Description
Pay	`payments:admin`	Grants all rights on payments.
Pay	`payments:read-only`	Only GET requests are allowed on payments.
Pay	`payments:allow-sensitive`	Grants read access on sensitive information for payments.
Pay	`payments:validate`	Allows to execute payments.
Pay	`payments:cancel`	Allows to submit payment cancellation requests.
Pay	`payments`	(Deprecated). Alias for `payments:admin`.

Pay

payments:admin

Grants all rights on payments.

Pay

payments:read-only

Only GET requests are allowed on payments.

Pay

payments:allow-sensitive

Grants read access on sensitive information for payments.

Pay

payments:validate

Allows to execute payments.

Pay

payments:cancel

Allows to submit payment cancellation requests.

Pay

payments

(Deprecated). Alias for payments:admin.

AuthServiceToken object

Property Type Description

Property	Type	Description
`token`	String	The generated service token.
`scope`	String	The service token dedicated scope.

token

String

The generated service token.

scope

String

The service token dedicated scope.

AuthRenewRequest object

Name Type Required Description

Name	Type	Required	Description
`grant_type`	String	Yes	The only accepted value is `client_credentials`.
`client_id`	String	Yes	The ID of the calling client application.
`client_secret`	String	Yes	The client secret associated with the client ID.
`id_user`	Integer	Yes	User for whom the token has to be generated. If not supplied, a user will be created.
`revoke_previous`	Boolean	No	If true, all other permanent tokens for the user will be deleted. The default is false.

grant_type

String

Yes

The only accepted value is client_credentials.

client_id

String

Yes

The ID of the calling client application.

client_secret

String

Yes

The client secret associated with the client ID.

id_user

Integer

Yes

User for whom the token has to be generated. If not supplied, a user will be created.

revoke_previous

Boolean

If true, all other permanent tokens for the user will be deleted. The default is false.

PreviousWebview NextUsers

Last updated 3 months ago