Axios with Vault

This article describes how to safely call external APIs from TAS calculations via the axios library while using secret keys stored in Vault (service tokens, API keys, passwords). Vault is available from version TAS 5.17.

Principle — why Vault instead of a hardcoded key

The vault.get('NAME') function does not return the secret key as readable text, but rather an opaque reference (VaultSecretRef). This reference cannot be logged, serialized, or printed — an attempt at JSON.stringify, .toString(), or writing it to a variable will only return [VaultSecretRef].

Prerequisites

• TAS version 5.17 or higher,
• a secret key created in Vault (Administration → Vault) under a specific name.

Basic procedure

Using Vault with axios always involves three steps:

1. Load the reference to the secret via vault.get('SECRET_NAME').
2. Create a client via axios.getAxios({ baseURL }).
3. Insert the reference into the request using one of the vault methods (setVaultHeader / setVaultQueryParam / requestWithVaultField).

Minimal example — Bearer token in the Authorization header:

// 1) reference to the secret from Vault
const tokenRef = vault.get('EXTERNAL_API_TOKEN');

// 2) client with base URL + 3) inserting the token into the header
const client = axios.getAxios({ baseURL: 'https://api.partner.com/v2' })
    .setVaultHeader('Authorization', tokenRef, 'Bearer ');

// call — TAS inserts the token internally only now
const response = client.get('/users/42');
return response.data;

Three ways to insert a secret

Choose the appropriate method depending on where the API expects the secret.

1. Into an HTTP header — setVaultHeader

The most common case: a Bearer token or API key in a header. The header is added to all subsequent requests of the given client.

// setVaultHeader(headerName, secretRef, prefix?)
const apiKeyRef = vault.get('PARTNER_API_KEY');

const client = axios.getAxios({ baseURL: 'https://api.partner.com' })
    .setVaultHeader('x-api-key', apiKeyRef);          // without prefix
    // or with prefix: .setVaultHeader('Authorization', apiKeyRef, 'Bearer ');

const response = client.get('/protected-resource');
return response.data;

2. Into a query parameter — setVaultQueryParam

For APIs that expect the key in the URL (e.g. ?apiKey=...). The parameter is automatically appended to every request of the client.

const apiKeyRef = vault.get('PUBLIC_API_KEY');

const client = axios.getAxios({ baseURL: 'https://api.example.com' })
    .setVaultQueryParam('apiKey', apiKeyRef);

// each request automatically contains ?apiKey=<resolved-secret>
const response = client.get('/results');
return response.data;

3. Into the request body — requestWithVaultField

When the API expects the secret directly in the body (typically an OAuth2 client_credentials flow with client_secret). The secret is inserted into the specified field in data without passing through the code.

const clientSecretRef = vault.get('OAUTH_CLIENT_SECRET');

const client = axios.getAxios({ baseURL: 'https://auth.example.com' });

// requestWithVaultField(config, [{ fieldName, ref }])
const tokens = client.requestWithVaultField(
    {
        method: 'POST',
        url: '/oauth/token',
        data: {
            grant_type: 'client_credentials',
            client_id: 'tas-service'
        }
    },
    [{ fieldName: 'client_secret', ref: clientSecretRef }]
);

return tokens.data.access_token;

Full response — requestRawWithVaultField

If, in addition to the data, you also need the status, statusText, or response headers, use the raw variant. Available from v5.7.37 (raw axios variants), vault fields from 5.17.

const secretRef = vault.get('SERVICE_PASSWORD');

const client = axios.getAxios({ baseURL: 'https://api.example.com' });

const raw = client.requestRawWithVaultField(
    {
        method: 'POST',
        url: '/login',
        data: { username: 'tas-service' }
    },
    [{ fieldName: 'password', ref: secretRef }]
);

if (raw.status !== 200) {
    proc.error('Login failed', { status: raw.status });
    debug.error('Login to the external service failed.');
}

return raw.data;

Complete example — OAuth2 token and a follow-up call

A typical scenario: obtaining an access token via a client_secret from Vault and using it for an authorized call.

// 1) reference to the client secret
const clientSecretRef = vault.get('OAUTH_CLIENT_SECRET');

const auth = axios.getAxios({ baseURL: 'https://auth.service.com' });

// 2) exchange for an access token (secret in the body)
const tokenResp = auth.requestWithVaultField(
    {
        method: 'POST',
        url: '/token',
        data: { grant_type: 'client_credentials', client_id: 'tas-service' }
    },
    [{ fieldName: 'client_secret', ref: clientSecretRef }]
);

const accessToken = tokenResp.data.access_token;

// 3) authorized call with the token in the header
const api = axios.getAxios({ baseURL: 'https://api.service.com' })
    .setVaultHeader('Authorization', accessToken, 'Bearer ');

const me = api.get('/me');
return me.data;

Logging and error handling

In TAS calculations, log exclusively via proc.info / proc.warn / proc.error — never console.log. To block a task with an error message, use debug.error.

const tokenRef = vault.get('EXTERNAL_API_TOKEN');
const client = axios.getAxios({ baseURL: 'https://api.example.com' })
    .setVaultHeader('Authorization', tokenRef, 'Bearer ');

try {
    const resp = client.post('/users', { email: vars['EMAIL'].getValue() });
    return resp.data;
} catch (err) {
    proc.error('API call failed', { message: err.message });
    debug.error('Failed to create the user in the external system.');
}

What not to do

Troubleshooting