The Airnode uses Airnode Authentication Security Schemes to authenticate itself to an API operation of which the values are known only by the Airnode.
The Airnode uses Relayed Meta Data Security Schemes to forward known information from the requester's request to an API operation.
Security schemes are declared by the required type property inside the security scheme definition. The following security scheme types are supported.
Airnode Authentication Security Schemes
Relayed Meta Data Security Schemes
It is important to note that the security schemes in any given OIS object apply to all endpoints/API operations in the OIS object. If different security schemes are required by a mix of endpoints/API operations, then more than one OIS object will be required grouping endpoint/API operations based on their security needs.
The apiKey security scheme type allows you to define an API key the Airnode will send to API operations. It is an object which consists of the following fields:
type must be apiKey
in can be one of the query, header or cookie. This value specifies how the value will be sent to an API operation. When using the query option, the API key will be sent in the request body for POST requests and in query string for GET requests.
name is the name of the API key that should be sent to an API. For example "X-Api-Key".
The value of the apiKey goes in the apiCredentials field of config.json designated by the proper oisTitle and securitySchemeName values, which is not part of the ois object, it exists in the root level of the config.json file. Normally the value is accessed using interpolation from the secrets.env file.
The http security scheme type is used to define either a basic or bearer authentication scheme. This security scheme will always be sent in the headers. The security scheme value should be base64 encoded value "username:password" for basic auth and the encoded token for bearer auth. It is an object which consists of the following fields:
The value of the http goes in the apiCredentials field of config.json designated by the proper oisTitle and securitySchemeName values, which is not part of the ois object, it exists in the root level of the config.json file. Normally the value is accessed using interpolation from the secrets.env file.
In addition to authenticating itself, Airnode can "relay" security information about a request to an API operation. This is different then the authorization of requesters using Authorizers to access the Airnode.
For relayed meta data security schemes do not provide any values in apiCredentials as they are extracted from the request by Airnode.
Note that Airnode relays this metadata to an API operation and does not perform any additional processing logic. The API provider must implement any desired logic in the API operation for any desired security checks. See Relayed Meta Data Authentication for overview of its usage.
Relay Metadata Tutorial
The relay-security-schemes monorepo example demonstrates how to relay request metadata like chain ID and sponsor address to the API endpoint.
The following example shows how to set up relayed meta data to forward the relayRequestId and relayChainId from Airnode to an AP operation. Note that unlike the Airnode authentication security scheme, no values are stored in apiCredentials as Airnode passes these known values to the API operation.
OIS security is inspired by OAS security practices. This is implemented using the security schemes and security field. All supported security schemes are described in detail in the Airnode Authentication Security Schemes and Relayed Meta Data Security Schemes sections above. The following example is related to Airnode Authentication Security Schemes. Working with security schemes can be described in three steps.
Use ois[n].apiSpecifications.components.securitySchemes to define the security schemes the API operation requires. Consider the partial config.json above that declares a security scheme named requiresXApiKey. This scheme declares that the API requires an API key that must exist in the HTTP header named X-api-key.
When the scheme is defined, it is not turned on by default. You need to explicitly list the security schemes you intend to use in the security field located in ois[n].apiSpecifications.security object. The keys in this object are the names of security schemes to be used. Use empty array () as its value.
Be aware that this step seems like extra work since there is no reason to define a security scheme that will not be used. However, Airnode may support more complex authentication logic in the future and using  allows its implementation without a breaking change.
Step #3: Specify the values for the defined security schemes
After defining and turning on a security scheme, it may be unclear what provides the value and how it is set.
The authentication schemes are intended to be common for the whole OIS and set by the API provider using apiCredentials which is part of config.json. The apiCredentials is an array which specifies the values for all security schemes in all OIS definitions. Each element of this array contains the following fields
oisTitle is the title of the OIS for the particular security scheme
securitySchemeName is the name of the security scheme
securitySchemeValue is the actual value that should be used by Airnode when making the API request. This value is usually a secret and it is recommended to interpolate it from secrets.env.
Currently, if you want different API operations to use different security schemes they must be grouped in different OIS objects based on their common security schemes. For example, your API has four operations, three require an API key in the HTTP header, another (public /ping endpoint) requires no security.
The first three API operations might be in the ois object with a security scheme named requiresXApiKey of type apiKey as shown above.
The /ping API operation would be in ois which would not have any component.securitySchemes and security would be an empty array.