Skip to main content

Key file authentication

In this guide, you will learn how to implement key file authentication, a secure method that uses a private key to sign JSON Web Tokens (JWTs). This method is especially suitable for server-to-server interactions where high security is necessary.

Throughout this guide, you will learn how to create a JWT header and payload, sign it using a private key, and authenticate the API. While the examples provided are based on cURL and command-line operations, the principles and techniques can be adapted to various programming languages, thanks to widely available libraries for handling HTTP requests and JWTs.

Prerequisites​

Before you start, complete the following prerequisites:

1. Generate a key file​

The first step involves generating a key file. This file contains your privateKey for signing tokens and the keyId necessary for creating a valid JWT header.

To generate the key file, follow these steps:

  1. Open MARCO Console.

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

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

  4. Click Generate a key to generate a new key file.

    Service account key

  5. Securely store the generated key file.

2. Prepare the JWT header​

Next, define the JWT header as follows:

{
    "alg": "RS256",
    "typ": "JWT",
    "kid": "<KEY_ID>"
}

Replace KEY_ID with the keyId found in the key file from step 1.

3. Prepare the JWT payload​

Define a JSON object for the JWT payload:

{
    "iss": "<APPLICATION_ID>",
    "sub": "<SERVICE_ACCOUNT_EMAIL>",
    "aud": "https://api-marco.finboot.com",
    "exp": <EXPIRATION_TIMESTAMP>,
    "jti": "<UUID>"
}

Replace:

  • APPLICATION_ID: The Marpp ID that issues the JWT. For example, MRP-m2uRgxpQd68.
  • SERVICE_ACCOUNT_EMAIL: The service account email. For example, test-4-service-account-58dcdb56@PRJ-ab3bae4e74f.mserviceaccount.finboot.com.
  • EXPIRATION_TIMESTAMP: The timestamp when the JWT will expire and should no longer be accepted for processing. It is formatted as a UTC UNIX timestamp (an integer). For example, 1703754932 corresponds to 2023-12-28 at 09:15:32 UTC. Typically, this is set to 1 minute in the future.
  • UUID: A unique identifier for the JWT. It can be generated using a UUID v4 generator. For example 186c65b8-56bd-4150-b182-8c2eabe1a9b4.

For additional information and details, refer to JSON Web Token (JWT).

## 4. Sign the JWT

For local development, you can sign the JWT using the command line with the jwt-cli package:

info

Before proceeding, ensure you have installed jwt-cli. For setup instructions, refer to the instalation instructions on npm.

jwt encode --secret='-----BEGIN RSA PRIVATE KEY-----
<PRIVATE_KEY>
-----END RSA PRIVATE KEY-----' \
--alg=RS256 \
--header='<JWT_HEADER>' \
--payload='<JWT_PAYLOAD>'

Replace:

  • PRIVATE_KEY: The private key located in the key file under privateKey.
  • JWT_HEADER: The JWT header you defined in step 2.
  • JWT_PAYLOAD: The JWT paylaod you defined in step 3.

This command will return the JWT encoded.

Alternatively, use the JWT Debugger utility in your browser or find a library for signing JWTs in your preferred programming language.

5. Authenticate with the signed JWT token​

Authenticate using the signed JWT with this curl command:

curl -X POST "https://api-marco.finboot.com/v1/auth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
     -d "client_assertion=<JWT_ENCODED>" \
     -d "client_id=<APPLICATION_ID>"

Replace:

  • JWT_ENCODED: The JWT encoded from step 4.
  • APPLICATION_ID: The Marpp ID that issues the JWT. For example, MRP-m2uRgxpQd68.

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 key files and JWTs in a secure location. Avoid exposing them or checking them into version control systems.
  • Token expiry: Ensure your JWTs have a reasonable expiration time to prevent potential misuse.

For more security recommendations, see Security best practices.