Secrets in the Reactor API

In the Reactor API, a secret is a resource that represents an authentication credential. Secrets are used in event forwarding to authenticate to another system for secure data exchange. Therefore, secrets can only be created within event forwarding properties (properties whose platform attribute is set to edge).

There are currently three supported secret types denoted in the type_of attribute:

This guide provides a high-level overview of how to configure secrets for use in event forwarding. For detailed guidance on how to manage secrets in the Reactor API, including example JSON of a secret’s structure, refer to the secrets endpoint guide.

Credentials

Each secret contains a credentials attribute that holds its respective credential values. When creating a secret in the API, each type of secret has different required attributes as shown in the sections below:

token token

Secrets with a type_of value of token only require a single attribute under credentials:

The token is stored as a static value, and therefore the secret’s expires_at and refresh_at properties are set to null when the secret is created.

simple-http simple-http

Secrets with a type_of value of simple-http require the following attributes under credentials:

When the secret is created, the two attributes are exchanged with a BASE64 encoding of username:password. After the exchange, the secret’s expires_at and refresh_at properties are set to null.

oauth2-client_credentials oauth2-client_credentials

Secrets with a type_of value of oauth2-client_credentials require the following attributes under credentials:

When an oauth2-client_credentials secret is created or updated, the client_id and client_secret (and possibly options) are exchanged in a POST request to the token_url, according to the Client Credentials flow of the OAuth protocol.

If the authorization service responds with 200 OK and a JSON response body, the body is parsed and the access_token is pushed to the edge environment and expires_in is used to calculate the expires_at and refresh_at attributes for the secret. If there is no environment association on the secret, access_token is discarded.

A credentials exchange is considered successful under the following conditions:

If the exchange is successful, the secret’s status attribute is set to succeeded and values for expires_at and refresh_at are set:

If the exchange fails for any reason, the status_details attribute in the meta object updates with relevant information.

Refreshing an oauth2-client_credentials secret

If an oauth2-client_credentials secret has been assigned to an environment and its status is succeeded (the credentials were exchanged successfully), a new exchange is performed automatically on refresh_at.

If the exchange is successful, the refresh_status attribute in the meta object is set to succeeded while expires_at, refresh_at, and activated_at are updated accordingly.

If the exchange fails, the operation is attempted three more times with the last attempt no more than two hours before the access token expires. If all attempts fail, the refresh_status_details attribute from the meta object updates with relevant details.

oauth2-google oauth2-google

Secrets with a type_of value of oauth2-google requires the following attribute under credentials:

After creating the oauth2-google secret, the response includes a meta.authorization_url property. You must copy and paste this URL into a browser to complete the Google authentication flow.

Reauthorize an oauth2-google secret

The authorization URL for an oauth2-google secret expires one hour after the secret is created (as indicated by meta.authorization_url_expires_at). After this time, the secret must be reauthorized in order to renew the authentication process.

Refer to the secrets endpoint guide for details on how reauthorize an oauth2-google secret by making a PATCH request to the Reactor API.

Environment relationship

When you create a secret, you must specify the environment in which it will exist. Secrets are immediately deployed to the environment in which they are created.

A secret can only be associated with one environment. Once the relationship between a secret and an environment is established, the secret cannot be cleared from the environment, and the secret cannot be associated with a different environment.

After a secret’s credentials have been successfully exchanged, for a secret to be associated with an environment, the exchange artifact (the token string for token, the Base64 encoded string for simple-http, or the access token for oauth2-client_credentials) is securely saved on the environment.

After the exchange artifact is successfully saved on the environment, the secret’s activated_at attribute is set to the current UTC time, and can now be referenced using a data element. See the next section for more information on referencing secrets.

Referencing secrets referencing-secrets

In order to reference a secret, you must create a data element of type “Secret” (provided by the Core extension) on an event forwarding property. When configuring this data element, you are prompted to indicate which secret to use for each environment. You can then create rules that reference a secret data element, such as within the header for an HTTP call.

At runtime, the secret data element is replaced with the corresponding secret exchange artifact saved on the environment.

Next steps

This guide covered the fundamentals of working with secrets in the Reactor API. For details on how to manage secrets using API calls, see the secrets endpoint guide.