Booya 2: API Documentation

Documentation

API Base URL

All endpoints have to be prefixed with your integration’s API  Base URL when making requests to the Booya 2.0 API. You can find the Base API URL for your integration by logging into https://go.booya.io/ and navigating to your Integration’s detail page. See the Booya 2.0 Installation guide for details on how to set up an integration.

Format: 

https://auth.booya.io/<app_id> 

Example:

https://auth.booya.io/inboundlabs where app_id is inboundlabs

API Endpoints

OAuth Sign In

GET /auth/signin/<provider>

 

Parameters

Name

Required

Type

Details

provider

True

URL

Either of: google, facebook, linkedin, twitter

grant_type

False

Query String

Default is code

code: A temporary authorization code that can be exchanged for an access token will be returned

Only code option is supported by this endpoint

redirect_uri

False

Query String

User will be redirect here on successful login

redirect_uri_error

False

Query String

User will be redirect here on failed login

 

This endpoint will redirect users to the appropriate OAuth provider, perform OAuth 2.0 Flow and then redirect them back to your website or specified redirect_uri parameter

Email/Password Sign In

POST /auth/signin

 

Parameters

Name

Required

Type

Details

email

True

Request Body

 

password

True

Request Body

 

grant_type

False

Request Body

Either of: code or token
Default is code

code: A temporary authorization code that can be exchanged for an access token will be returned

token: A short-lived access token will be returned

 

Email/Password Registration

POST /auth/register

 

Parameters

Name

Required

Type

Details

email

True

Request Body

 

password

True

Request Body

 

first_name

True

Request Body

 

last_name

True

Request Body

 

next_url

False

Request Body

User will be redirected here by account verification email

 

An email with a account verification link will be sent to the new user’s email

 

Verify Authentication/Token

POST /auth/verify

 

Parameters

 

Name

Required

Type

Details

token

True

Request Body

This is either the authorization code received from the OAuth or email/password sign in endpoints or an access token previously received from this, the token exchange or sign in endpoints

 

The response body will contain user information. 

IMPORTANT: A short-lived access-token will be returned as well if an authorization code was sent in the initial request.

 

NOTE: An Authorization header e.g Authorization: Bearer <token> can be sent in place of the 

token in the body.

 

Token/Code Exchange

POST /auth/token

 

Parameters

 

Name

Required

Type

Details

code

True if token is not sent

Request Body

This is an authorization code received from the OAuth or Email/Password sign in endpoints

token

True if code is not sent

Request Body

This is an an access token received from this, the token verification or email/password sign in endpoints

appSecret

False

Request Body

appSecret for your integration. 
It should only be included in requests from secure environments like your backend, it must never be sent from a browser.

 

The response body will contain a short-lived access-token for the user.
A long-lived token refresh token will also be returned if the appSecret was sent in the initial request.

IMPORTANT: The appSecret should only be included in requests from secure environments like your backend, it should never be sent from a browser.

 

NOTE: For requests exchanging a short-lived token for another short-lived token, the appSecret must be included otherwise the same token will be returned. This means short-lived tokens can only be refreshed from secure environments like your backend.

Verify Account

POST /auth/verify/account

 

Parameters

 

Name

Required

Type

Details

token

True

Request Body

This is the one time token sent via the account verification email

 

 

Resend Verification Email

POST /auth/resend-verification

 

Parameters

Name

Required

Type

email

True

Request Body

 

Log Out or Revoke Token

POST /auth/logout

POST /auth/revoke

 

Parameters

Name

Required

Type

token

True

Request Body

 

Recover Account

POST /auth/recover

 

Parameters

Name

Required

Type

email

True

Request Body

 

An email with a password reset link will be sent to the specified email

 

Change Password

POST /auth/change-password

 

Parameters

 

Name

Required

Type

Details

token

True

Request Body

This is the one time password/token sent via the password reset email

password

True

Request Body

This is the new password to set