Home
API reference
Platform API reference
Platform API
Credentials
Create auth credential

Create auth credential

post/v1/authcredentials
Page View

Credential endpoints allow you to manage custom authentication strategies for your organization's destinations. Destinations are the endpoints in your system that receive data from Redox.

You may choose custom authentication for your destinations if you want more secure authentication credentials for any data coming into your system.

With this set of Platform API endpoints, you can:

  • retrieve a list of existing auth credentials for an environment;
  • retrieve one auth credential by its ID;
  • retrieve a list of supported auth strategies;
  • create a new auth credential;
  • update an existing auth credential; or
  • delete an existing auth credential.

Create auth credential

Create a new auth credential that you can use to verify your destination(s).

The response contains details of the new auth credential but doesn't include any secret values. Instead, secrets are replaced with boolean fields that indicate whether a secret value exists with a true or false value. The field name has the format of has<PropertyName>.

Request parameters and payload

cURL request example

bash
1
curl 'https://api.redoxengine.com/platform/v1/authcredentials' \
2
--request POST \
3
--header 'Authorization: Bearer $API_TOKEN' \
4
--header 'accept: application/json' \
5
--header 'content-type: application/json' \
6
--data '{
7
  "organization": 118,
8
  "name": "Sample Auth Credential",
9
  "environmentId": "a31a92e5-43b7-45df-8085-4ac5a746d105",
10
  "grantType": "client_credentials",
11
  "url": "string",
12
  "grantTypeName": "grant_type",
13
  "clientIdName": "client_id",
14
  "clientSecretName": "client_secret",
15
  "refreshTokenName": "refresh_token",
16
  "clientId": "string",
17
  "clientSecret": "zzzSecret-assigned-by-authorization-server!!",
18
  "accessTokenName": "string",
19
  "expiresFieldName": "string",
20
  "refreshGrantType": "string",
21
  "audience": "string",
22
  "scopes": "string",
23
  "contentType": "string",
24
  "noBasic": "string",
25
  "resource": "string",
26
  "customFieldName": "string",
27
  "customFieldValue": "string",
28
  "defaultExpirationSeconds": "string",
29
  "basicNoForm": true
30
}'

Request Body Schema

    This is an authentication strategy type that uses an OAuth client, authorization server, and system server. The OAuth client requests an access token from the authorization server. The returned access token can be used to access the system server.

  • grantType
    required, string
    Value: client_credentials
  • url
    required, string

    Enter the URL where the client requests an access token. It’s usually provided by the authorization server and varies by auth strategy. Redox passes credentials to this URL for auth strategies other than OAuth. For SAML/SOAP auth, this may not be used.

  • grantTypeName
    string

    Enter the parameter name used to specify the grant type in the access token request body (e.g., grant_type or grantType).

  • clientIdName
    string

    Enter the key name for sending the client ID in a token request (e.g., client_id or clientId).

  • clientSecretName
    string

    Enter the key name for sending the client secret in a token request (e.g., client_secret or clientSecret).

  • refreshTokenName
    string

    Specify the name used to pass a refresh token when requesting a new access token (e.g., refresh_token or refreshToken).

  • clientId
    string

    Provide the unique identifier assigned to a client application by the authorization server. This identifies which application is making the authentication request.

  • clientSecret
    string

    Provide the confidential key for authenticating the client application. It’s like a password for the app, which is required in cases where the client must prove its identity.

  • accessTokenName
    string

    Specify the name used to pass the access token in the API request (e.g., access_token or accessToken). It’s typically included in the request header.

  • expiresFieldName
    string

    Define the name of the field that specifies an access token expires (e.g., expires or expires_in). This is used to track when the access token will no longer be valid to make API requests.

  • refreshGrantType
    string

    Specify the grant type used for refreshing an expired token (e.g., refresh_token or refresh).

  • audience
    string

    Specify the intended recipient of the access token. This is typically the URI of the resource server.

  • scopes
    string

    Define what permissions the application is requesting from the user. In some cases, scopes limit access to specific resources or actions.

  • contentType
    string

    Indicate the format of the request body (e.g., application/x-www-form-urlencoded or application/json).

  • noBasic
    string

    Set to true to suppress sending the auth object in OAuth requests

  • resource
    string

    Enter the URI that represents the resource the client is trying to access. In some cases, it defines the target for access token issuance.

  • customFieldName
    string

    Define the name of the custom parameter that may be required by a specific implementation.

  • customFieldValue
    string

    Specify the value for the custom parameter, which may be required by a specific implementation. Some APIs or systems may require additional fields in the access token request.

  • defaultExpirationSeconds
    string

    Define the default duration (in seconds) that an access token remains valid before it needs to be refreshed or reissued.

  • basicNoForm
    boolean

    If enabled, the client_id and client_secret will not be included in the form data, only grant_type

Response fields and example

Example payload generated from schema
1
{
2
  "meta": {
3
    "version": "1.0.0"
4
  },
5
  "payload": {
6
    "id": "string",
7
    "createdAt": "string",
8
    "updatedAt": "string",
9
    "hasClientSecret": "",
10
    "organization": 118,
11
    "name": "Sample Auth Credential",
12
    "environmentId": "a31a92e5-43b7-45df-8085-4ac5a746d105",
13
    "grantType": "client_credentials",
14
    "url": "string",
15
    "grantTypeName": "grant_type",
16
    "clientIdName": "client_id",
17
    "clientSecretName": "client_secret",
18
    "refreshTokenName": "refresh_token",
19
    "clientId": "string",
20
    "clientSecret": "string",
21
    "accessTokenName": "string",
22
    "expiresFieldName": "string",
23
    "refreshGrantType": "string",
24
    "audience": "string",
25
    "scopes": "string",
26
    "contentType": "string",
27
    "noBasic": "string",
28
    "resource": "string",
29
    "customFieldName": "string",
30
    "customFieldValue": "string",
31
    "defaultExpirationSeconds": "string",
32
    "basicNoForm": true
33
  }
34
}
  • meta
    object
    • version
      string

      Lists the major and minor version number for the format of the returned payload. The payload format or shape may change between minor versions, like including additional or extended fields in later versions. We include the version data in each response so that you have the option to handle the signaled differences.

  • payload

      This is an authentication strategy type that uses an OAuth client, authorization server, and system server. The OAuth client requests an access token from the authorization server. The returned access token can be used to access the system server.

    • grantType
      required, string
      Value: client_credentials
    • url
      required, string

      Enter the URL where the client requests an access token. It’s usually provided by the authorization server and varies by auth strategy. Redox passes credentials to this URL for auth strategies other than OAuth. For SAML/SOAP auth, this may not be used.

    • grantTypeName
      string

      Enter the parameter name used to specify the grant type in the access token request body (e.g., grant_type or grantType).

    • clientIdName
      string

      Enter the key name for sending the client ID in a token request (e.g., client_id or clientId).

    • clientSecretName
      string

      Enter the key name for sending the client secret in a token request (e.g., client_secret or clientSecret).

    • refreshTokenName
      string

      Specify the name used to pass a refresh token when requesting a new access token (e.g., refresh_token or refreshToken).

    • clientId
      string

      Provide the unique identifier assigned to a client application by the authorization server. This identifies which application is making the authentication request.

    • clientSecret
      string

      Provide the confidential key for authenticating the client application. It’s like a password for the app, which is required in cases where the client must prove its identity.

    • accessTokenName
      string

      Specify the name used to pass the access token in the API request (e.g., access_token or accessToken). It’s typically included in the request header.

    • expiresFieldName
      string

      Define the name of the field that specifies an access token expires (e.g., expires or expires_in). This is used to track when the access token will no longer be valid to make API requests.

    • refreshGrantType
      string

      Specify the grant type used for refreshing an expired token (e.g., refresh_token or refresh).

    • audience
      string

      Specify the intended recipient of the access token. This is typically the URI of the resource server.

    • scopes
      string

      Define what permissions the application is requesting from the user. In some cases, scopes limit access to specific resources or actions.

    • contentType
      string

      Indicate the format of the request body (e.g., application/x-www-form-urlencoded or application/json).

    • noBasic
      string

      Set to true to suppress sending the auth object in OAuth requests

    • resource
      string

      Enter the URI that represents the resource the client is trying to access. In some cases, it defines the target for access token issuance.

    • customFieldName
      string

      Define the name of the custom parameter that may be required by a specific implementation.

    • customFieldValue
      string

      Specify the value for the custom parameter, which may be required by a specific implementation. Some APIs or systems may require additional fields in the access token request.

    • defaultExpirationSeconds
      string

      Define the default duration (in seconds) that an access token remains valid before it needs to be refreshed or reissued.

    • basicNoForm
      boolean

      If enabled, the client_id and client_secret will not be included in the form data, only grant_type