Authentication
The Authenticator defines how to configure outgoing HTTP requests to authenticate on the API source.
Schema:
Authenticator:
type: object
description: "Authenticator type"
anyOf:
- "$ref": "#/definitions/OAuth"
- "$ref": "#/definitions/ApiKeyAuthenticator"
- "$ref": "#/definitions/BearerAuthenticator"
- "$ref": "#/definitions/BasicHttpAuthenticator"
Authenticators
ApiKeyAuthenticator
The ApiKeyAuthenticator sets an HTTP header on outgoing requests.
The following definition will set the header "Authorization" with a value "Bearer hello":
Schema:
ApiKeyAuthenticator:
type: object
additionalProperties: true
required:
- header
- api_token
properties:
"$parameters":
"$ref": "#/definitions/$parameters"
header:
type: string
api_token:
type: string
Example:
authenticator:
type: "ApiKeyAuthenticator"
header: "Authorization"
api_token: "Bearer hello"
For more information see ApiKeyAuthenticator Reference
BearerAuthenticator
The BearerAuthenticator is a specialized ApiKeyAuthenticator that always sets the header "Authorization" with the value Bearer {token}.
The following definition will set the header "Authorization" with a value "Bearer hello"
Schema:
BearerAuthenticator:
type: object
additionalProperties: true
required:
- api_token
properties:
"$parameters":
"$ref": "#/definitions/$parameters"
api_token:
type: string
Example:
authenticator:
type: "BearerAuthenticator"
api_token: "hello"
More information on bearer authentication can be found here.
For more information see BearerAuthenticator Reference
BasicHttpAuthenticator
The BasicHttpAuthenticator set the "Authorization" header with a (USER ID/password) pair, encoded using base64 as per RFC 7617.
The following definition will set the header "Authorization" with a value Basic {encoded credentials}
Schema:
BasicHttpAuthenticator:
type: object
additionalProperties: true
required:
- username
properties:
"$parameters":
"$ref": "#/definitions/$parameters"
username:
type: string
password:
type: string
Example:
authenticator:
type: "BasicHttpAuthenticator"
username: "hello"
password: "world"
The password is optional. Authenticating with APIs using Basic HTTP and a single API key can be done as:
Example:
authenticator:
type: "BasicHttpAuthenticator"
username: "hello"
For more information see BasicHttpAuthenticator Reference
OAuth
The OAuth authenticator is a declarative way to authenticate with an API using OAuth 2.0.
To learn more about the OAuth authenticator, see the OAuth 2.0 documentation.
JWT Authenticator
JSON Web Token (JWT) authentication is supported through the JwtAuthenticator.
Schema
JwtAuthenticator:
title: JWT Authenticator
description: Authenticator for requests using JWT authentication flow.
type: object
required:
- type
- secret_key
- algorithm
properties:
type:
type: string
enum: [JwtAuthenticator]
secret_key:
type: string
description: Secret used to sign the JSON web token.
examples:
- "{{ config['secret_key'] }}"
base64_encode_secret_key:
type: boolean
description: When set to true, the secret key will be base64 encoded prior to being encoded as part of the JWT. Only set to "true" when required by the API.
default: False
algorithm:
type: string
description: Algorithm used to sign the JSON web token.
enum:
[
"HS256",
"HS384",
"HS512",
"ES256",
"ES256K",
"ES384",
"ES512",
"RS256",
"RS384",
"RS512",
"PS256",
"PS384",
"PS512",
"EdDSA",
]
examples:
- ES256
- HS256
- RS256
- "{{ config['algorithm'] }}"
token_duration:
type: integer
title: Token Duration
description: The amount of time in seconds a JWT token can be valid after being issued.
default: 1200
examples:
- 1200
- 3600
header_prefix:
type: string
title: Header Prefix
description: The prefix to be used within the Authentication header.
examples:
- "Bearer"
- "Basic"
jwt_headers:
type: object
title: JWT Headers
description: JWT headers used when signing JSON web token.
additionalProperties: false
properties:
kid:
type: string
title: Key Identifier
description: Private key ID for user account.
examples:
- "{{ config['kid'] }}"
typ:
type: string
title: Type
description: The media type of the complete JWT.
default: JWT
examples:
- JWT
cty:
type: string
title: Content Type
description: Content type of JWT header.
examples:
- JWT
additional_jwt_headers:
type: object
title: Additional JWT Headers
description: Additional headers to be included with the JWT headers object.
additionalProperties: true
jwt_payload:
type: object
title: JWT Payload
description: JWT Payload used when signing JSON web token.
additionalProperties: false
properties:
iss:
type: string
title: Issuer
description: The user/principal that issued the JWT. Commonly a value unique to the user.
examples:
- "{{ config['iss'] }}"
sub:
type: string
title: Subject
description: The subject of the JWT. Commonly defined by the API.
aud:
type: string
title: Audience
description: The recipient that the JWT is intended for. Commonly defined by the API.
examples:
- "appstoreconnect-v1"
additional_jwt_payload:
type: object
title: Additional JWT Payload Properties
description: Additional properties to be added to the JWT payload.
additionalProperties: true
$parameters:
type: object
additionalProperties: true
Example:
authenticator:
type: JwtAuthenticator
secret_key: "{{ config['secret_key'] }}"
base64_encode_secret_key: True
algorithm: RS256
token_duration: 3600
header_prefix: Bearer
jwt_headers:
kid: "{{ config['kid'] }}"
cty: "JWT"
additional_jwt_headers:
test: "{{ config['test']}}"
jwt_payload:
iss: "{{ config['iss'] }}"
sub: "sub value"
aud: "aud value"
additional_jwt_payload:
test: "test custom payload"
For more information see JwtAuthenticator Reference