🔐 Authentication
Last updated

API Authentication Guide

The Boya API uses API keys for authentication. This guide will walk you through the process of generating an API key or requesting one via email, explain the different Usage Plans available, and provide information about the API's Base URL.

Table of Contents

Base URL

All API requests should be made to the following base URL:

https://api.boyahq.com/v1

When making requests to the Boya API, append the specific endpoint paths to this base URL. For example, to access the users endpoint, you would use:

${BASE_URL}/teams

Remember to include the appropriate headers and API key with each request as described in the Using the API Key section.

Authentication Overview

To authenticate and access Boya's API, each request must include a valid API key. The API key serves as a unique identifier, allowing the API to verify your identity and grant access to the requested resources.

Important Notes:

  • Keep your API key secure: Do not share your API key with others or expose it in public repositories.
  • Rate limits: Each API key has specific rate limits. Refer to our rate limit policy for more details.

Generating an API Key

To generate an API key, you must have access to the Boya Admin Dashboard. Follow these steps to generate your API key:

Steps:

  1. Log in to the Boya Admin Dashboard: Navigate to Boya Admin Dashboard and sign in with your credentials.
  2. Access the API Settings: In the dashboard, go to the "Settings" section and select the "API KEYS" tab.
  3. Generate New API Key:
    • Click the "Generate API Key" button.
    • Provide a name or description for your API key (e.g., "ERP Integration Key").
    • Select the appropriate Usage Plan for your API key (see API Key Usage Plans section).
    • Click "Create" to generate your key.
  4. Copy the API Key: Once generated, your new API key will be displayed. Copy it immediately and store it in a secure location, as it will not be shown again.

Example:

After following the steps above, your API key might look like this: APIKEY: 3fbd-47df-842f-f015e7c90e9942956808

Requesting an API Key via Email

If you cannot access the Boya Admin Dashboard, you can request an API key via email.

Steps:

  1. Send an email to the Boya Support Team: Compose an email requesting a new API key. Use the following format:

    To: apisupport@boyahq.com
    Subject: API Key Request

    Body:

    Dear Api Team, I would like to request an API key for accessing the Boya API. My account details are as follows:

    • Name: [Your Name] • Company: [Your Company Name] • Email: [Your Email Address] • Requested Usage Plan: [Specify the desired Usage Plan]

    Please provide the necessary steps or generate an API key for me.

    Thank you, [Your Name]

  2. Wait for Confirmation: The Boya support team will respond within 1-2 business days with your API key or further instructions.

Using the API Key

Once you have obtained your API key, include it in the header of each API request you make.

HTTP Request Headers:

Add the following header to your request:

x-api-key: <your-api-key>

Example using Javascript:

fetch("https://api.boyahq.com/v1/users", {
  method: "GET",
  headers: {
    "x-api-key": "<api-key>",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

Managing API Keys

You can manage your API keys in the Boya Admin Dashboard:

  1. View Active Keys: In the "API KEYS" tab, you will see a list of your active keys.
  2. Revoke API Keys: If an API key is compromised or no longer in use, you can revoke it by clicking the "Revoke" button next to the key.
  3. Generate New Keys: You can generate multiple keys for different applications (e.g., web, mobile) and manage them individually.
  4. Update Usage Plans: You can modify the Usage Plan associated with an existing API key if your access requirements change.

API Key Usage Plans

When generating or requesting an API key, you can specify a Usage Plan that determines the level of access and permissions associated with the key. The available Usage Plans are:

  1. Read-Only

    • Allows read access to all information available via the API
    • Includes access to expenses, statements, and employee data
    • Cannot perform any write or modification operations

  2. Make-Payments

    • Includes all permissions from the Read-Only plan
    • Allows initiation and authorization of payments
    • Can view and manage payment-related information

  3. Allocations

    • Includes all permissions from the Read-Only plan
    • Allows allocation of money from business wallets or personal wallets
    • Can manage and view allocation-related data

  4. Issue-Card

    • Includes all permissions from the Read-Only plan
    • Allows issuing of new cards
    • Can manage and view card-related information

When requesting or generating an API key, specify the desired Usage Plan based on your integration needs. If your requirements change, you can request an update to your API key's Usage Plan through the Boya Admin Dashboard or by contacting support.

Troubleshooting

If you encounter any issues with your API key:

  • Ensure that the key is correctly included in your request header.
  • Verify that you're using the correct Base URL (https://api.boyahq.com/v1) for all API requests.
  • Check if the API key has been revoked.
  • Verify that your API key's Usage Plan allows the operation you're attempting.
  • Check API response for rate-limits.
  • Contact support at support@boyahq.com for further assistance.
Previous page
Next page