• 28 Sep 2023
  • 14 Minutes to read
  • PDF


  • PDF

Article Summary

Traceable's API security testing (AST) provides you with an option to add an authentication mechanism to AST scans. This is helpful in cases where authentication is short-lived or has expired. In such cases, the AST scans are not completed. For example, if you are running a scan on live traffic after a long duration of time, there is a possibility that the authentication would have expired or DAST scans where requests are made using OpenAPI spec. In such a case, the scan would not complete. It may also be possible that if you are running a scan on old data or suppressed data, the authentication tokens are also suppressed. In such cases, AST would need a fresh authentication token to complete the scan. 

Traceable supports multiple authentication mechanisms, such as:

Each authentication method and profile can be associated with one of the following roles. 

  • Standard
  • Admin
  • Reader
  • Writer

In Traceable Platform, click on Testing SettingsAuthentications to set up authentication. The following sections explain each of the authentication mechanisms and their associated configuration.

The topic assumes that you have reasonable knowledge of authentication mechanisms. The following sections give only a brief description of different types of authentication mechanism.

For each of the authentication mechanisms, give a Name and Description (optional). This is the name by which you would identify the authentication mechanism when you generate a scan with authentication. You can also test all the configured authentication mechanisms (except OAuth) to determine whether your hook compiles correctly with the provided inputs. AST provides you with a toggle option to switch to Advance mode, using which you can write your custom script for each authentication mechanism.

The different authentication type forms have an option to provide a value template. This value template should be in the form of bearer: {{value}}.


An authentication mechanism based on API Key is a security method used in software development and web services. It involves generating and providing a unique alphanumeric key (API Key) to identify and authenticate the user or application accessing an API. The server verifies the key before granting access.


API Key authentication mechanism has the following configurations:

API KeyThe unique key generated for the user or the applications.
Add API Key as part of Query parameterQuery Key - A Query Key, in the context of API Key authentication, is a specific type of API Key that is transmitted as part of the URL or query parameters when making an API request. It is one of the common methods for passing an API Key to an API server for authentication and authorization.
When using a Query Key, the API Key is appended to the URL as a parameter, typically in the following format:
In this example, "api_key" is the query parameter name, and "your_api_key_here" is the actual API Key associated with your application or user account. The API server extracts the API Key from the query parameters and uses it to authenticate and authorize the request.
Query value template(optional) - A Query Value Template in API Key authentication is a mechanism that allows you to dynamically substitute a value into a predefined query parameter in the API request URL. This is often used to insert an API Key or other authentication credentials into the request.

Here's an example of how a Query Value Template might be used:

Let us say you have an API endpoint that requires an API Key, and the API Key is provided using a Query Value Template:{API_KEY}
In this template, {API_KEY} is a placeholder for the actual API Key. When making a request to the API, you would replace {API_KEY}with the real API Key:
By using a Query Value Template, you can keep the actual API Key separate from the code logic and easily update it when necessary. It also allows for better security practices, since the API Key is not exposed in plaintext within the codebase.
Add API Key as part of HeaderHeader key - In API Key authentication, a “header key” typically refers to the method of including the API Key as a value in an HTTP header when making API requests. This method is frequently used to secure API endpoints by transmitting authentication credentials in the HTTP headers rather than as part of the URL or request body.
Header value template(optional) - A "header value template" in API Key authentication is a concept where you use a template or a placeholder in an HTTP header's value and dynamically substitute it with the actual API Key or authentication token when making API requests. This approach is often used to enhance security and flexibility when transmitting authentication credentials in HTTP headers.

Here's how a header value template works:

  1. Template in the Header Value: Instead of hard-coding the actual API Key or authentication token directly into the header, you use a template or placeholder, which is typically enclosed in curly braces or some other distinctive format. For example:
    Authorization: Bearer {{API_KEY}}
    In this example, {API_KEY} is a template for the actual API Key.
  2. Dynamic Replacement: When you make an API request, your application, or code dynamically replaces {API_KEY} with the real API Key or authentication token before sending the request to the API server. This ensures that the actual authentication credential is used in the header.

Example Request with Header Value Template:

GET /api/resource HTTP/1.1
Authorization: Bearer your_actual_api_key_here

By using a header value template, you can separate the API Key from the code logic and easily update it when necessary without changing the code. It also adds an extra layer of security by preventing the API Key from being exposed in plaintext within the codebase.

The specific syntax and conventions for header value templates may vary depending on the API and its documentation.

Add API Key as part of CookieCookie key - The value of the cookie required for authentication. Cookie key is not a standard authentication mechanism in API key authentication.
Cookies are small pieces of data sent by a web server and stored on a user's device, typically a web browser. They are often used for session management, tracking user preferences, and maintaining state between HTTP requests. Cookies are not commonly used to transmit API Keys or other sensitive authentication information because they are more susceptible to various security vulnerabilities like cross-site scripting (XSS) attacks and cross-site request forgery (CSRF) attacks.
Cookie value template (optional) - A template to add cookie value like in templates for Query parameter and Header.

Basic Auth

Basic Auth, short for Basic Authentication, is a simple and widely used method for securing web resources, APIs, and other online services. It provides a way for clients (typically, web browsers or software applications) to authenticate themselves to a server by sending a username and password in the form of a header in an HTTP request. The username and password are Base64 encoded.


Basic Auth mechanism has the following configurations:

UsernameThe username of the user or the application.
PasswordThe password for the user or application.
Header Value Template (optional)Basic Authentication works by directly encoding the username:password pair into a base64 string and placing it in the Authorizationheader as follows:
Authorization: Basic {{value}}


In authentication mechanisms, a bearer refers to a type of token that is used to prove the identity of a user or system. Bearer tokens are a common method of implementing authentication in various contexts, including web applications, APIs, and network protocols. The term bearer signifies that whoever possesses the token is considered the authenticated entity, without further verification. Bearer tokens are straightforward to implement but come with some security concerns. Since anyone with possession of the token is considered authenticated, it is crucial to protect bearer tokens from unauthorized access or interception.


Bearer mechanism has the following configurations:

Bearer TokenThe token string representing the user's authentication and authorization claims.
Add token as part of query parameterYou can add a bearer token as part of a query parameter in an HTTP request.
This practice is generally discouraged because it exposes the token in the URL, making it visible in various logs, browser history, and potentially to other users or attackers. Instead, it is much more secure to use the Authorization header for transmitting bearer tokens. If, for some reason, you still need to pass the token as a query parameter, you can do so by appending it to the URL like this:
GET /api/resource?token=your-bearer-token
Add token as part of headerAdding a bearer token as part of the header is the recommended and standard practice for bearer token authentication in HTTP requests. Bearer tokens are typically included in the Authorization header of the request. Here's how you can do it:
GET /api/resource HTTP/1.1
Authorization: bearer {{eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9}}
Add token as part of cookie

Bearer tokens are typically not stored in cookies for security reasons, as storing sensitive authentication tokens like bearer tokens in cookies can introduce various security risks, such as cross-site scripting (XSS) attacks and cross-site request forgery (CSRF) attacks. It is typically recommended to use the Authorization header for transmitting bearer tokens, as it is a more secure and standard approach.

However, if you still want to store a bearer token in a cookie, you can do so by setting a cookie using server-side code.


HMAC (Hash-based Message Authentication Code) is a mechanism used for verifying the authenticity and integrity of a message or piece of data. It is commonly used in various authentication and security protocols, including web application security, API authentication, and more. HMAC relies on a cryptographic hash function and a secret key to generate a unique code that can be used to verify the data has not been tampered with.


Bearer mechanism has the following configurations:

Access KeyThe unique identifier for the user or application.
Secret KeyThe secret key, also known as the HMAC key, is a confidential cryptographic key that is used to both generate and verify HMAC values. This key is shared between the sender and receiver.
AlgorithmChoose from one of the following:
  • HMAC SHA 256
  • HMAC SHA 512
Signature headerThe signature header is often implemented as part of an Authorization header in HTTP requests. This is a common practice for securing API endpoints using HMAC for authentication and data integrity verification.
Timestamp Header (optional)Including a timestamp header in HMAC authentication is a common practice to enhance security and prevent replay attacks. When a timestamp is included in HMAC-based authentication, it ensures that requests are only considered valid for a limited period of time.
Canonical Request Format (optional){HTTP_METHOD}, {RESOURCE}, {QUERY_PARAMETERS}, {HEADERS}, {PAYLOAD}
A canonical request format is a standardized representation of an HTTP request that is used as the input for generating the HMAC signature. The canonical request format ensures consistency in how the request data is prepared for HMAC calculation, which is essential for both the sender and receiver to compute and verify the HMAC accurately.

JSON Web Tokens (JWT)

JWT is a compact, URL-safe, and self-contained method for securely transmitting information between parties. JWTs contain claims, which are statements about an entity, and are signed by the server. The client sends the JWT in the Authorization header with each API request, allowing the server to verify the token's authenticity and grant access based on the encoded claims.


JWT authentication mechanism has the following configurations:

Explicit Token

An explicit token typically refers to a specific type of token that carries clear and explicit information about the user or entity it represents. It is a way to make JWTs more self-contained by including detailed user information in the token's payload, rather than relying on the server to look up user data based on the token's subject (sub) claim.

TokenThe JSON Web Token string containing the signed claims.
Add token as part of Query ParameterYou can technically include a token as part of a query parameter if needed. However, it's essential to use this approach with caution and ensure you follow best practices to mitigate security risks.
Add token as part of HeaderJWT is commonly used as part of the HTTP header, specifically the Authorization header, in web applications and APIs to provide authentication and authorization for requests. Including JWTs in the header allows for secure transmission of tokens between clients and servers.
Add token as part of CookieCookie key - JWT authentication mechanisms that involve cookies, the cookie key refers to the name or identifier used for the cookie that stores the JWT token. When the server sends a JWT to the client to be stored as a cookie, it must specify the name of the cookie so that both the client and server can access and manipulate it correctly.

Dynamic Token

A dynamic token in JWT authentication typically refers to a token that is generated or modified dynamically based on certain conditions, user actions, or specific requirements. Dynamic tokens can be a powerful tool in authentication and authorization systems, as they allow for flexibility and adaptability to various scenarios.

Secret KeyThe secret key plays a crucial role in securing the tokens, including dynamic tokens. The secret key is used for signing and verifying the integrity of the tokens, ensuring that they have not been tampered with by malicious parties.
AlgorithmChoose from SHA 256 or SHA 1
Add ClaimIn JWT, a claim is a piece of information or a statement about an entity (typically, the user) encoded in the token. Claims are used to convey information about the token, such as the identity of the user, the token's expiration time, or additional user-related data like roles and permissions. Claims are included in the token's payload and help define the token's purpose and its permissions.
Claims are represented as key-value pairs within the JWT's payload, which is a JSON object. Here's an example of a JWT payload containing claims:
  "sub": "1234567890",
  "name": "John Doe",
  "role": "user",
  "exp": 1632086400
In this example: 
  • The sub claim identifies the subject (user) as "1234567890."
  • The name claim provides the user's name as "John Doe."
  • The role claim specifies that the user has a role of "user."
  • The exp claim indicates that the token is valid until a certain expiration timestamp (e.g., 1632086400).

For Adding token as Query parameter, Header, or Cookie, see explanation in Explicit Token section.

Mutual TLS

Mutual Transport Layer Security (mTLS) is a method that involves client and server authentication using SSL/TLS certificates. Both parties verify each other's certificates, ensuring secure communication and establishing a trusted relationship.


mTLS authentication mechanism has the following configurations:

Client CertificateA client certificate in Mutual TLS authentication is a digital certificate presented by the client during the TLS handshake to prove its identity to the server. This certificate is used with the server's certificate to establish a secure and authenticated communication channel. The certificate should be in a supported format, for example, PEM, DER, PKCS#12.
Client KeyA client key in mTLS refers to the private key associated with the client's digital certificate.
Client Key PassphraseThe client key passphrase in mTLS is a passphrase or password used to protect the private key associated with the client's digital certificate.
Client Authority CertificateA bundle of trusted CA certificates for validating the server's certificate.


OAuth is a popular open standard for access delegation. It allows users to grant third-party applications limited access to their resources without sharing their credentials. OAuth 2.0, the latest version, uses access tokens to authenticate API requests.


OAuth's authentication mechanism has the following configurations:

Token EndpointIt is a URL or endpoint provided by the Authorization Server (the server responsible for issuing access tokens in OAuth) where authorized clients can exchange authorization codes, refresh tokens, or other credentials for access tokens.
Authorization EndpointThe Authorization Endpoint in OAuth 2.0 is where the user's authentication and consent process begins, allowing clients to request access to protected resources while ensuring that users have control over which resources they share with third-party applications.
Callback URLThe Callback URL (Redirect URI) in OAuth 2.0 is the endpoint where the client receives the response from the Authorization Server after the user has authenticated and authorized the client's access to resources.
Client Auth MethodChoose from Basic Auth or Request body
Scope (optional)The permissions requested by the client.

Generate the token after you have filled the configurations listed above. You can then add the token as part of a Query Parameter, Header, or Cookie.

OAuth authentication mechanism does not support testing.

POP Token Signature

PoP (Proof of Possession) tokens are a type of security token that contains a cryptographic key, which the client uses to sign each API request. The server validates the signature to ensure that the client is in possession of the corresponding private key.


PoP's authentication mechanism has the following configurations:

Private KeyA private key is a confidential cryptographic key used to prove ownership and possession of a specific key when creating digital signatures.
Header KeyA header key refers to a name used to identify and convey information about the token or the request in which it is included. It typically refers to a key or value included in the header of an HTTP request or a token that is used to provide information about the request or token itself. The header key can be a part of the metadata or header information that accompanies the token to convey additional details or instructions.
Header Value Template{{value}}

Content Signature

Content Signature is a method of authentication where the body of the request (the content) is hashed and signed using a private key. The signature is then included in the request, typically as a header. The server verifies the signature using the corresponding public key. If the signature is valid, the server processes the request; otherwise, it rejects it.


Content signature authentication mechanism has the following configurations:

Header KeyThe hashed content signature.
Private KeyThe key to generating the digital signature.


If you have an authentication that is not among the one's mentioned above, you can write your mechanism by choosing Custom from the drop-down list.

Was this article helpful?