Skip to main content

API key authentication

In this guide, you will learn how to authenticate your application or service account using an API key, often referred to as token-based authentication.

info

For production environments, we recommend using Key file authentication.

Prerequisites​

Before you start, complete the following prerequisites:

1. Generate an API token​

To generate an API token for your service account, follow these steps:

  1. Open MARCO Console.

  2. Go to the IAM > Service accounts > List acounts section on the left sidebar.

  3. Select a service account and access the Service Account API Keys tab.

  4. Click Generate API key.

    Service account token

  5. Note down your API token and the service account email. You will need these details for any API interactions.

2. Get the access token​

To authenticate your service account using cURL and the OAuth 2.0 client credentials flow, you will need the following details:

  • Application ID (<YOUR_APPLICATION_ID>): Represents the Marpp ID of the application that you are trying to access resources with.
  • API Key (<YOUR_API_KEY>): The unique key you generated in the previous section.
  • Service Account (<YOUR_SERVICE_ACCOUNT>): The identifier for the service account you are using for authentication.

Use the details above in the following cURL command:

curl -X POST "https://api-marco.finboot.com/v1/auth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=<APPLICATION_ID>" \
     -d "client_secret=<API_TOKEN>" \
     -d "grant_type=client_credentials" \
     -d "service_account=<SERVICE_ACCOUNT_EMAIL>"

Replace:

  • APPLICATION_ID: The Marpp ID that issues the JWT. For example, MRP-m2uRgxpQd68.
  • API_TOKEN: The unique key you generated in the previous section.
  • SERVICE_ACCOUNT_EMAIL: The email for the service account you are using for authentication. For example, test-4-service-account-58dcdb56@PRJ-ab3bae4e74f.mserviceaccount.finboot.com.

This command interacts with the Obtain an access token endpoint to authenticate your application. It will return a JSON object containing an access token:

{
    "access_token": "eyJra...w4lqw",
    "token_type": "Bearer",
    "expires_in": 299
}
caution

The access token expires has a lifespan of 300 seconds (5 minutes) To maintain uninterrupted use of the API, ensure to generate a new access token each time the current one expires.

Now that you have successfully authenticated, see HTTP Requests to learn how to use this access token in your API calls.

Best practices​

Maintain the security of your API keys by following these guidelines:

  • Secure storage: Always store your API keys securely, preferably using environment variables or secret management tools.
  • Key rotation: Rotate your API keys periodically to ensure security.
  • Avoid hardcoding: Never embed API keys directly in your codebase.
  • Monitor usage: Regularly monitor the usage of your API keys to detect any unauthorized access.

For more security recommendations, see Security best practices.