Home
API reference
Platform API reference
Platform API
Credentials
Update auth credential

Update auth credential

patch/v1/authcredentials/{id}
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.

Update auth credential

Update field values of an existing auth credential.

The response contains the auth credential with the new values. The payload 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/{id}' \
2
--request PATCH \
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": "",
12
  "clientId": "",
13
  "audience": "",
14
  "scopes": "",
15
  "authStrategy": "OAuth_2.0_2-legged",
16
  "grantTypeName": "",
17
  "refreshGrantType": "refresh_token",
18
  "clientIdName": "",
19
  "accessTokenName": "",
20
  "expiresFieldName": "",
21
  "refreshTokenName": "",
22
  "contentType": "application/x-www-form-urlencoded",
23
  "noBasic": "true",
24
  "resource": "",
25
  "customFieldName": "",
26
  "customFieldValue": "",
27
  "defaultExpirationSeconds": "3600",
28
  "clientSecret": "zzzSecret-assigned-by-authorization-server!!"
29
}'

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.

  • organization
    required, number

    Contains your unique Redox organization identifier.

  • name
    required, string

    Displays the name of the auth credential.

  • environmentId
    required, string

    Identifies the specific environment that the auth credential is used in.

  • grantType
    required, string

    Indicates the method that's used to grant access to and authenticate the OAuth client. Redox only supports client_credentials.

  • url
    required, string

    Contains the authorization server URL, where the authorization request is sent.

  • clientId
    required, string

    Identifies the OAuth client. This value is assigned by the authorization server.

  • authStrategy
    required, string

    Indicates the specific strategy type that this auth credential belongs to.

    Value: OAuth_2.0_2-legged
  • audience
    string

    Indicates the system that should consume the auth credentials. This field isn't required but is sent in the audience field of the authorization request when populated.

  • scopes
    string

    Defines the scope or access granted with the authentication credentials. This field isn't required but is sent in the scope field of the authorization request when populated.

  • grantTypeName
    string

    Contains the property name for the grant_type field in the authorization request. The default value is grant_type. This field is an advanced option that should be used if the authorization server expects something other than grant_type.

  • refreshGrantType
    string

    Indicates the value sent in the grant_type field. This must be set when requesting a refresh token. Refresh tokens aren't often used with a client_credential grant.

  • clientIdName
    string

    Contains the property name for the client_id field in the authorization request. The default value is client_id. This field is an advanced option that should be used if the authorization server expects something other than client_id.

  • accessTokenName
    string

    Contains the property name for the access_token field in the authorization response. The default value is access_token. This field is an advanced option that should be used if the authorization server responds with something other than access_token.

  • expiresFieldName
    string

    Contains the property name for the expires_in field in the authorization response. The default value is expires_in. This field is an advanced option that should be used if the authorization server responds with something other than expires_in.

  • refreshTokenName
    string

    Contains the property name for the refresh_token field in the authorization response. The default value is refresh_token. This field is an advanced option that should be used if the authorization server responds with something other than refresh_token.

  • contentType
    string

    Defines the default type of payload for requests coming into your system with this auth credential. This value is located in the header of incoming API requests. The default value is application/x-www-form-urlencoded.

  • noBasic
    string

    Some servers expect a basic auth header, including the client ID and secret, in the authorization request. The default behavior is to always send the basic auth header. Setting this field to true excludes the basic auth header from the request.

  • resource
    string

    Identifies a specific resource that the OAuth client is requesting access to. This field isn't required but is sent in the resource field of the authorization request when populated.

  • customFieldName
    string

    Defines an additional field that the OAuth client can send in the authorization request, either in the header or body. To add a custom field to the header, it must start with headers., otherwise it will appear in the body.

  • customFieldValue
    string

    Contains the value of the customFieldName, which is sent in the authorization request.

  • defaultExpirationSeconds
    string

    Defines the number of seconds that the access token is valid, if used. This field is only used if the authorization server doesn't send an expiration value in the response.

  • clientSecret
    string

    Contains the secret value assigned by the authorization server.

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": "",
15
    "clientId": "",
16
    "audience": "",
17
    "scopes": "",
18
    "authStrategy": "OAuth_2.0_2-legged",
19
    "grantTypeName": "",
20
    "refreshGrantType": "refresh_token",
21
    "clientIdName": "",
22
    "accessTokenName": "",
23
    "expiresFieldName": "",
24
    "refreshTokenName": "",
25
    "contentType": "application/x-www-form-urlencoded",
26
    "noBasic": "true",
27
    "resource": "",
28
    "customFieldName": "",
29
    "customFieldValue": "",
30
    "defaultExpirationSeconds": "3600"
31
  }
32
}
  • 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.

    • id
      required, string

      Contains a unique identifier assigned to the auth credential. Use this value when querying for this auth credential in future API requests.

    • createdAt
      required, string

      Displays the timestamp of when the auth credential was created. This value is set by Redox.

    • updatedAt
      required, string

      Displays the timestamp of the last time this auth credential was updated. This value is set by Redox.

    • organization
      required, number

      Contains your unique Redox organization identifier.

    • name
      required, string

      Displays the name of the auth credential.

    • environmentId
      required, string

      Identifies the specific environment that the auth credential is used in.

    • grantType
      required, string

      Indicates the method that's used to grant access to and authenticate the OAuth client. Redox only supports client_credentials.

    • url
      required, string

      Contains the authorization server URL, where the authorization request is sent.

    • clientId
      required, string

      Identifies the OAuth client. This value is assigned by the authorization server.

    • authStrategy
      required, string

      Indicates the specific strategy type that this auth credential belongs to.

      Value: OAuth_2.0_2-legged
    • hasClientSecret
      boolean

      Indicates whether the auth credential has a client secret stored. If so, this is set to true.

    • audience
      string

      Indicates the system that should consume the auth credentials. This field isn't required but is sent in the audience field of the authorization request when populated.

    • scopes
      string

      Defines the scope or access granted with the authentication credentials. This field isn't required but is sent in the scope field of the authorization request when populated.

    • grantTypeName
      string

      Contains the property name for the grant_type field in the authorization request. The default value is grant_type. This field is an advanced option that should be used if the authorization server expects something other than grant_type.

    • refreshGrantType
      string

      Indicates the value sent in the grant_type field. This must be set when requesting a refresh token. Refresh tokens aren't often used with a client_credential grant.

    • clientIdName
      string

      Contains the property name for the client_id field in the authorization request. The default value is client_id. This field is an advanced option that should be used if the authorization server expects something other than client_id.

    • accessTokenName
      string

      Contains the property name for the access_token field in the authorization response. The default value is access_token. This field is an advanced option that should be used if the authorization server responds with something other than access_token.

    • expiresFieldName
      string

      Contains the property name for the expires_in field in the authorization response. The default value is expires_in. This field is an advanced option that should be used if the authorization server responds with something other than expires_in.

    • refreshTokenName
      string

      Contains the property name for the refresh_token field in the authorization response. The default value is refresh_token. This field is an advanced option that should be used if the authorization server responds with something other than refresh_token.

    • contentType
      string

      Defines the default type of payload for requests coming into your system with this auth credential. This value is located in the header of incoming API requests. The default value is application/x-www-form-urlencoded.

    • noBasic
      string

      Some servers expect a basic auth header, including the client ID and secret, in the authorization request. The default behavior is to always send the basic auth header. Setting this field to true excludes the basic auth header from the request.

    • resource
      string

      Identifies a specific resource that the OAuth client is requesting access to. This field isn't required but is sent in the resource field of the authorization request when populated.

    • customFieldName
      string

      Defines an additional field that the OAuth client can send in the authorization request, either in the header or body. To add a custom field to the header, it must start with headers., otherwise it will appear in the body.

    • customFieldValue
      string

      Contains the value of the customFieldName, which is sent in the authorization request.

    • defaultExpirationSeconds
      string

      Defines the number of seconds that the access token is valid, if used. This field is only used if the authorization server doesn't send an expiration value in the response.