Skip to content

Create a credential rotation

Request

Replaces the access token of a shared GitLab, Azure DevOps, or Bitbucket token credential. Redocly validates the new token with the Git provider before saving it. Rotating any other credential type returns 400.

To find the credentialId, list the sources or remotes of the project that uses the credential.

Only shared credentials can be rotated with an API key. Personal credentials return 404. Use an API key with granular permissions that include org.credentials.update, or a legacy full access key. API keys with RBAC permissions return 403.

After saving the token, Redocly sets up webhooks again for the repositories that use the credential. Repositories where the webhook setup fails are listed in warnings.

Requires org.credentials.update permission.

Security
ApiKey
Path
orgIdstring^org_[0-9abcdefghjkmnpqrstvwxyz]{26}$required
Organization ID.
Example:org_01h1s5z6vf2mm1mz3hevnn9va7
Headers
x-redocly-clientstring^[a-z0-9-]{1,64}/[\w.+-]{1,32}$

Identifies the calling client as <name>/<version>, for example reunite-ui/0.92.1. Used for API consumer observability. Requests without it are attributed as unknown.

Example:reunite-ui/0.92.1
Bodyapplication/jsonrequired
credentialIdstring^cred_[0-9abcdefghjkmnpqrstvwxyz]{26}$required

ID of the credential whose access token is replaced. Unique identifier prefixed with cred_.

Example:"cred_01h1s5z6vf2mm1mz3hevnn9va7"
secretDataobject(AccessTokenCredential)write-onlyrequired
New access token for the credential.
curl -i -X POST \
  https://redocly.com/_mock/docs/platform/customization/reunite-api/openapi/orgs/org_01h1s5z6vf2mm1mz3hevnn9va7/credential-rotations \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'x-redocly-client: reunite-ui/0.92.1' \
  -d '{
    "credentialId": "cred_01h1s5z6vf2mm1mz3hevnn9va7",
    "secretData": {
      "accessToken": "string"
    }
  }'

Responses

Credential access token replaced.
Bodyapplication/json
idstring^cred_[0-9abcdefghjkmnpqrstvwxyz]{26}$read-onlyrequired

Credential ID. Unique identifier prefixed with cred_.

Example:"cred_01h1s5z6vf2mm1mz3hevnn9va7"
objectstringread-onlyrequired
Entity name.
Value:"credential"
uristring, (uri)read-onlyrequired
Canonical URI for the credential resource.
Example:"https://app.cloud.redocly.com/api/orgs/org_01hh1t9sa6gwfv5naz04gr7ehm/credentials/cred_01h1s5z6vf2mm1mz3hevnn9va7"
typestring, (enum)(CredentialType)required
Credential type.
Enum:"GITHUB_USER""GITLAB_USER""BITBUCKET_USER""AZURE_USER""URL""GITHUB_CLOUD_APP_INSTALLATION""GITHUB_SERVER_APP_INSTALLATION""GITHUB_SERVER_APP""GITLAB_SELF_MANAGED_APP""GITHUB_CLOUD_INTERNAL_APP_INSTALLATION"
authTypestring, (enum)(AuthType)
Credential auth type.
Enum:"BASIC""PERSONAL_ACCESS_TOKEN""PERSONAL_ACCESS_TOKEN_FOR_ORGANIZATION""PROJECT_ACCESS_TOKEN""INSTALLATION_ACCESS_TOKEN""OAUTH2""BEARER""API_KEY"
namestring
descriptionstring
publicDataGitHubInstallationPublicCredential (object) or GitHubEEServerAppPublicCredential (object) or GitLabSelfManagedAppPublicCredential (object) or AzureDevOpsUserPATPublicCredential (object) or BitbucketCloudUserProjectTokenPublicCredential (object) or McpPublicCredential (object)
One of:
Credential public data.
oAuth2Dataobjectread-only
Credential OAuth2 data.
userIdstring^usr_[0-9abcdefghjkmnpqrstvwxyz]{26}$read-only

User ID this credentials belongs to. Unique identifier prefixed with usr_.

Example:"usr_01hh1t9sa6gwfv5naz04gr7ehm"
isSharedboolean
Default:false
isBrokenbooleanread-only
Default:false
parentIdstring^cred_[0-9abcdefghjkmnpqrstvwxyz]{26}$

Credential parent ID. Unique identifier prefixed with cred_.

Example:"cred_01h4e71x94vd68a1farnbfapzg"
createdAtstring, (date-time)read-onlyrequired
updatedAtstring, (date-time)read-onlyrequired
warningsArray of stringsread-onlyrequired
Problems that do not block the update. For example, Redocly cannot set up a webhook for a repository that uses this credential.
Example:
[
  "Failed to set up webhook for repository \"fe5d7747-af71-449a-951b-f781f54603af\": Azure DevOps token does not have sufficient permissions. Please check token scopes."
]
Response
{
  "id": "cred_01h1s5z6vf2mm1mz3hevnn9va7",
  "object": "credential",
  "uri": "https://app.cloud.redocly.com/api/orgs/org_01hh1t9sa6gwfv5naz04gr7ehm/credentials/cred_01h1s5z6vf2mm1mz3hevnn9va7",
  "type": "GITHUB_USER",
  "authType": "BASIC",
  "name": "string",
  "description": "string",
  "publicData": {
    "installationId": 0,
    "namespaceId": "string",
    "repositoryId": "string"
  },
  "oAuth2Data": {
    "id": "4acc1f09-1751-6f79-b156-b6877ee205a2",
    "userName": "john-doe",
    "displayName": "John Doe",
    "email": "john-doe@mail.com",
    "avatarUrl": "https://avatars.githubusercontent.com/u/1?v=4"
  },
  "userId": "usr_01hh1t9sa6gwfv5naz04gr7ehm",
  "isShared": false,
  "isBroken": false,
  "parentId": "cred_01h4e71x94vd68a1farnbfapzg",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "warnings": [
    "Failed to set up webhook for repository \"fe5d7747-af71-449a-951b-f781f54603af\": Azure DevOps token does not have sufficient permissions. Please check token scopes."
  ]
}