Ping Identity logo
API docs by Redocly

Identity Cloud API (1.0.0)

Download OpenAPI specification:Download

Introduction

The Identity Cloud REST API lets customers manage their Identity Cloud tenant. The API exposes access management and identity management endpoints, with additional endpoints specific to Identity Cloud tenant environments.

We are now publishing the API spec in OpenAPI 3.0. For the legacy Swagger 2.0 spec, please download swagger.yaml, but note that it may not contain all new functionality.

For Identity Cloud documentation, please visit Backstage.

Authenticating to the API

The Identity Cloud REST API has two different authentication methods:

  • API key and secret: used for tenant read-only operations
  • Access token: used for access management operations, identity management operations or tenant write operations

For a summary of how to use these authentication methods, refer to Authenticate to Identity Cloud REST API.

Environment Secrets and Variables

Environment secrets and variables (ESVs) let you individually configure the development, staging, and production environments in your Identity Cloud tenant.

Variables

Variables are used to set configuration values that need to be different for each tenant environment. For example, an external service might need one URL in your development environment, but a different URL in your production environment.

Variables are not versioned, and can be read back. They should not contain secrets.

Variables are injected into Identity Cloud configuration when the underlying services are started or restarted.

Get all variables

Authorizations:
OAuth2
query Parameters
_pageSize
integer [ 1 .. 100 ]
Default: 25

Accept-API-Version: resource=2.0 only, maximum number of results returned by endpoint before paging

_pagedResultsCookie
string
Default: ""

Accept-API-Version: resource=2.0 only, opaque data used for paging result data, can be used for paging instead of having to track pageSize and pagedResultsOffset

_pagedResultsOffset
integer >= 0
Default: 0

Accept-API-Version: resource=2.0 only, offset of the first result to be returned by endpoint

_onlyPending
boolean
Default: false

Accept-API-Version: resource=2.0 only, returns ESVs with unapplied changes

header Parameters
Accept-API-Version
string

resource=2.0

Responses

Response samples

Content type
application/json
Example
{
  • "pagedResultsCookie": null,
  • "remainingPagedResults": 0,
  • "result": [
    ],
  • "resultCount": 4,
  • "totalPagedResults": 1,
  • "totalPagedResultsPolicy": "string"
}

Delete a variable

Authorizations:
OAuth2
path Parameters
variableId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the variable

header Parameters
Accept-API-Version
string

resource=2.0

Responses

Response samples

Content type
application/json
{
  • "_id": "esv-myvariable1",
  • "description": "My variable",
  • "expressionType": "list",
  • "lastChangeDate": "1999-12-31T23:59:59Z",
  • "lastChangedBy": "bjensen",
  • "loaded": false,
  • "valueBase64": "ZGF0YQ=="
}

Get a variable

Authorizations:
OAuth2
path Parameters
variableId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the variable

header Parameters
Accept-API-Version
string

resource=2.0

Responses

Response samples

Content type
application/json
{
  • "_id": "esv-myvariable1",
  • "description": "My variable",
  • "expressionType": "list",
  • "lastChangeDate": "1999-12-31T23:59:59Z",
  • "lastChangedBy": "bjensen",
  • "loaded": false,
  • "valueBase64": "ZGF0YQ=="
}

Set a variable description

Authorizations:
OAuth2
path Parameters
variableId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the variable

query Parameters
_action
required
string
Value: "setDescription"
header Parameters
Accept-API-Version
string

resource=2.0

Request Body schema: application/json
required

The description of this variable

description
required
string <= 1000 characters

Responses

Request samples

Content type
application/json
{
  • "description": "My secret"
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "unauthorized"
}

Create or update a variable

Create or update a variable using a predefined name. Once created, a variable name cannot be changed.

Authorizations:
OAuth2
path Parameters
variableId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the variable

header Parameters
Accept-API-Version
string

resource=2.0

Request Body schema: application/json
required

JSON body of the new variable

description
string <= 1000 characters
expressionType
string
Enum: "string" "list" "array" "object" "bool" "int" "number" "base64encodedinlined" "keyvaluelist"
valueBase64
required
string <byte> ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[...

Responses

Request samples

Content type
application/json
{
  • "description": "My variable",
  • "expressionType": "array",
  • "valueBase64": "ZGF0YQ=="
}

Response samples

Content type
application/json
{
  • "_id": "esv-myvariable1",
  • "description": "My variable",
  • "expressionType": "list",
  • "lastChangeDate": "1999-12-31T23:59:59Z",
  • "lastChangedBy": "bjensen",
  • "loaded": false,
  • "valueBase64": "ZGF0YQ=="
}

Secrets

Secrets are used to set configuration values that need encrypting. The values may or may not need to be different for each tenant environment. Authorization passwords and authentication signing keys are examples of secrets that might exist in your configuration.

Secrets can have multiple versions enabled to allow rotation, and once set they cannot be read back.

Secrets are injected into Identity Cloud configuration when the underlying services are started or restarted.

Get all secrets

Get all secrets, but not their secret versions or secret version values.

Authorizations:
OAuth2
query Parameters
_pageSize
integer [ 1 .. 100 ]
Default: 25

Accept-API-Version: resource=2.0 only, maximum number of results returned by endpoint before paging

_pagedResultsCookie
string
Default: ""

Accept-API-Version: resource=2.0 only, opaque data used for paging result data, can be used for paging instead of having to track pageSize and pagedResultsOffset

_pagedResultsOffset
integer >= 0
Default: 0

Accept-API-Version: resource=2.0 only, offset of the first result to be returned by endpoint

_onlyPending
boolean
Default: false

Accept-API-Version: resource=2.0 only, returns ESVs with unapplied changes

header Parameters
Accept-API-Version
string

resource=2.0

Responses

Response samples

Content type
application/json
{
  • "pagedResultsCookie": "null",
  • "remainingPagedResults": 0,
  • "result": [
    ],
  • "resultCount": 4,
  • "totalPagedResults": 1,
  • "totalPagedResultsPolicy": "string"
}

Delete a secret

Delete a secret and all its secret versions and secret version values.

Authorizations:
OAuth2
path Parameters
secretId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the secret

header Parameters
Accept-API-Version
string

resource=2.0

Responses

Response samples

Content type
application/json
{
  • "_id": "esv-mysecret1",
  • "activeVersion": "1",
  • "description": "My secret",
  • "encoding": "generic",
  • "lastChangeDate": "1999-12-31T23:59:59Z",
  • "lastChangedBy": "bjensen",
  • "loaded": true,
  • "loadedVersion": "1",
  • "useInPlaceholders": true
}

Get a secret

Get a secret, but not its secret versions or secret version values.

Authorizations:
OAuth2
path Parameters
secretId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the secret

header Parameters
Accept-API-Version
string

resource=2.0

Responses

Response samples

Content type
application/json
{
  • "_id": "esv-mysecret1",
  • "activeVersion": "1",
  • "description": "My secret",
  • "encoding": "generic",
  • "lastChangeDate": "1999-12-31T23:59:59Z",
  • "lastChangedBy": "bjensen",
  • "loaded": true,
  • "loadedVersion": "1",
  • "useInPlaceholders": true
}

Set a secret description

Authorizations:
OAuth2
path Parameters
secretId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the secret

query Parameters
_action
required
string
Value: "setDescription"
Request Body schema: application/json
required

The description of this secret

description
required
string <= 1000 characters

Responses

Request samples

Content type
application/json
{
  • "description": "My secret"
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "unauthorized"
}

Create a secret

Create a secret and its first secret version.

Authorizations:
OAuth2
path Parameters
secretId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the secret

header Parameters
Accept-API-Version
string

resource=2.0

Request Body schema: application/json
required

JSON body of the new secret

description
string <= 1000 characters
encoding
required
string
Enum: "generic" "pem" "base64hmac" "base64aes"
useInPlaceholders
required
boolean
valueBase64
required
string <byte> ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[...

Responses

Request samples

Content type
application/json
{
  • "description": "My secret",
  • "encoding": "generic",
  • "useInPlaceholders": true,
  • "valueBase64": "ZGF0YQ=="
}

Response samples

Content type
application/json
{
  • "_id": "esv-mysecret1",
  • "activeVersion": "1",
  • "description": "My secret",
  • "encoding": "generic",
  • "lastChangeDate": "1999-12-31T23:59:59Z",
  • "lastChangedBy": "bjensen",
  • "loaded": true,
  • "loadedVersion": "1",
  • "useInPlaceholders": true
}

Get all versions of a secret

Get all versions and version metadata of a secret. It is not possible to view the secret values.

Authorizations:
OAuth2
path Parameters
secretId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the secret

header Parameters
Accept-API-Version
string

resource=2.0

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new version of a secret

Authorizations:
OAuth2
path Parameters
secretId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the secret

query Parameters
_action
required
string
Value: "create"

Can only be create

header Parameters
Accept-API-Version
string

resource=2.0

Request Body schema: application/json
required

JSON body of the new secret version

valueBase64
required
string <byte> ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[...

Responses

Request samples

Content type
application/json
{
  • "valueBase64": "ZGF0YQ=="
}

Response samples

Content type
application/json
{
  • "createDate": "1999-12-31T23:59:59Z",
  • "loaded": false,
  • "status": "DISABLED",
  • "version": "latest"
}

Delete a version of a secret

Authorizations:
OAuth2
path Parameters
secretId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the secret

versionId
required
string^latest$|^[0-9]+$

ID of the secret version

header Parameters
Accept-API-Version
string

resource=2.0

Responses

Response samples

Content type
application/json
{
  • "createDate": "1999-12-31T23:59:59Z",
  • "loaded": false,
  • "status": "DISABLED",
  • "version": "latest"
}

Get a version of a secret

Get a version and version metadata of a secret. It is not possible to view the secret value.

Authorizations:
OAuth2
path Parameters
secretId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the secret

versionId
required
string^latest$|^[0-9]+$

ID of the secret version

header Parameters
Accept-API-Version
string

resource=2.0

Responses

Response samples

Content type
application/json
{
  • "createDate": "1999-12-31T23:59:59Z",
  • "loaded": false,
  • "status": "DISABLED",
  • "version": "latest"
}

Update the status of a version of a secret

Update the status of a version of a secret to either ENABLED or DISABLED. The latest version of a secret cannot be updated to a status of DISABLED.

Authorizations:
OAuth2
path Parameters
secretId
required
string^esv-[a-z0-9_-]{1,124}$

ID of the secret

versionId
required
string^latest$|^[0-9]+$

ID of the secret version

query Parameters
_action
required
string
Value: "changestatus"

Can only be changestatus

header Parameters
Accept-API-Version
string

resource=2.0

Request Body schema: application/json
required

JSON body of the new status of the secret version

status
required
string
Enum: "DISABLED" "ENABLED"

Responses

Request samples

Content type
application/json
{
  • "status": "DISABLED"
}

Response samples

Content type
application/json
{
  • "createDate": "1999-12-31T23:59:59Z",
  • "loaded": false,
  • "status": "DISABLED",
  • "version": "latest"
}

Restart

A restart of Identity Cloud services is used when new variables or secrets have been created and need to be injected into Identity Cloud configuration.

Get restart status

Get restart status indicating whether any upgrade or rollout restart is taking place on Identity Cloud services.

Authorizations:
OAuth2
header Parameters
Accept-API-Version
string

resource=2.0

Responses

Response samples

Content type
application/json
{
  • "restartStatus": "restarting"
}

Initiate restart

Initiate restart of Identity Cloud services. This will inject any new variables or secrets into Identity Cloud configuration.

Authorizations:
OAuth2
query Parameters
_action
required
string
Value: "restart"

Can only be restart

header Parameters
Accept-API-Version
string

resource=2.0

Responses

Response samples

Content type
application/json
{
  • "restartStatus": "restarting"
}

Count

Count is used to quickly identify how many variables and secrets are in an environment.

Get count of ESVs

Get count of ESV secrets and variables in the environment.

Authorizations:
OAuth2
query Parameters
_onlyPending
boolean
Default: false

Accept-API-Version: resource=2.0 only, returns ESVs with unapplied changes

header Parameters
Accept-API-Version
string

resource=2.0

Responses

Response samples

Content type
application/json
{
  • "secrets": 10,
  • "variables": 0
}

Config Promotions

Identity Cloud lets you run self-service promotions to move configuration between a sequential pair of tenant environments.

Promotion

API endpoints related to self-service promotions

Lock environments

Starts the lock process on the lower and upper environments

Authorizations:
OAuth2
header Parameters
Accept-API-Version
required
string

protocol=1.0,resource=1.0

Responses

Response samples

Content type
application/json
{
  • "description": "Environment lock in progress",
  • "promotionId": "ba594bbe-a589-4676-80a4-42975a56f5b6",
  • "result": "locking"
}

Unlock environments

Start the unlock process on the lower and upper environments.

Authorizations:
OAuth2
path Parameters
promotionId
required
string

Promotion unique identifier

header Parameters
Accept-API-Version
required
string

protocol=1.0,resource=1.0

Responses

Response samples

Content type
application/json
{
  • "description": "Environment unlocked",
  • "promotionId": "ba594bbe-a589-4676-80a4-42975a56f5b6",
  • "result": "unlocked"
}

Get lock status

Get the lock status of the lower and upper environments.

Authorizations:
OAuth2
query Parameters
localLockOnly
boolean

If set to true this parameter will only return the lock status of the environment the request is aimed at

header Parameters
Accept-API-Version
required
string

protocol=1.0,resource=1.0

Responses

Response samples

Content type
application/json
{
  • "description": "<meaningful when result=Error>",
  • "lowerEnv": {
    },
  • "promotionId": "ba594bbe-a589-4676-80a4-42975a56f5b6",
  • "result": "locked",
  • "upperEnv": {
    }
}

Get promotion status

Get the status of a promotion, if one is in progress.

Authorizations:
OAuth2
header Parameters
Accept-API-Version
required
string

protocol=1.0,resource=1.0

Responses

Response samples

Content type
application/json
{
  • "blockingError": false,
  • "encryptedSecrets": [
    ],
  • "globalLock": "LOCKED",
  • "message": "Environment ready for promotion",
  • "missingESVs": [
    ],
  • "promotionId": "7e7634c3-406e-4d37-80a3-d34461c2f309",
  • "status": "READY",
  • "timeStamp": "2022-02-01T14:17:02+01:00",
  • "type": "promotion"
}

Run a promotion

Promote configuration from the lower environment to the upper environment.

Authorizations:
OAuth2
header Parameters
Accept-API-Version
required
string

protocol=1.0,resource=1.0

Request Body schema: application/json
required

A request body with info required to initiate a promotion

dryRun
required
boolean

A boolean denoting whether this a dry run

ignoreEncryptedSecrets
boolean

A boolean denoting whether or not to ignore encrypted secrets detected in config during the promotion

promoter
string

The name of the admin user who initiated the promotion

promotionDescription
string

Promoter specified note to make it easier for them to identify what was promoted

unlockEnvironmentsAfterPromotion
boolean

A boolean denoting whether or not to automatically unlock the environments after a successful promotion

zendeskTicketReference
string

A string denoting the Zendesk ticket reference to be added to the promotion commit message

Responses

Request samples

Content type
application/json
{
  • "dryRun": true,
  • "ignoreEncryptedSecrets": true,
  • "promoter": "string",
  • "promotionDescription": "string",
  • "unlockEnvironmentsAfterPromotion": true,
  • "zendeskTicketReference": "string"
}

Response samples

Content type
application/json
{
  • "result": "Promotion Complete"
}

Get last promotion report

This will return the contents of the last run config promotion report

Authorizations:
OAuth2
header Parameters
Accept-API-Version
required
string

protocol=1.0,resource=1.0

Responses

Response samples

Content type
application/json
{
  • "createdDate": "2022-01-27T15-23+00Z",
  • "dryRun": true,
  • "missingESVs": [
    ],
  • "previouslyIgnoredEncryptedSecrets": [
    ],
  • "promoter": "Barb Jensen",
  • "promotionDescription": "Promoting our Forgotten Username journey",
  • "promotionId": "da0c66a4-9f37-4f9a-9988-0786ad301b17",
  • "report": {
    },
  • "reportId": "da0c66a4-9f37-4f9a-9988-0786ad301b17",
  • "reportName": "Report_2022-01-27T15-23+00Z_dryrun=true_a7456dd2-1acd-4bd9-8555-d44b2275a2da",
  • "type": "promotion"
}

Get a promotion report

Get a specific promotion report.

Authorizations:
OAuth2
path Parameters
reportId
required
string

Promotion report unique identifier

header Parameters
Accept-API-Version
required
string

protocol=1.0,resource=1.0

Responses

Response samples

Content type
application/json
{
  • "createdDate": "2022-01-27T15-23+00Z",
  • "dryRun": true,
  • "missingESVs": [
    ],
  • "previouslyIgnoredEncryptedSecrets": [
    ],
  • "promoter": "Barb Jensen",
  • "promotionDescription": "Promoting our Forgotten Username journey",
  • "promotionId": "da0c66a4-9f37-4f9a-9988-0786ad301b17",
  • "report": {
    },
  • "reportId": "da0c66a4-9f37-4f9a-9988-0786ad301b17",
  • "reportName": "Report_2022-01-27T15-23+00Z_dryrun=true_a7456dd2-1acd-4bd9-8555-d44b2275a2da",
  • "type": "promotion"
}

Get a provisional promotion report

Get a provisional report of changes since the last time the lower environment was promoted to the upper environment. The report generated is for informational purposes only and may not reflect all the changes in a full promotion. A dry-run promotion is always recommended prior to a full promotion between environments.

Authorizations:
OAuth2
header Parameters
Accept-API-Version
required
string

protocol=1.0,resource=1.0

Responses

Response samples

Content type
application/json
{
  • "createdDate": "2022-01-27T15-23+00Z",
  • "dryRun": true,
  • "missingESVs": [
    ],
  • "previouslyIgnoredEncryptedSecrets": [
    ],
  • "promoter": "Barb Jensen",
  • "promotionDescription": "Promoting our Forgotten Username journey",
  • "promotionId": "da0c66a4-9f37-4f9a-9988-0786ad301b17",
  • "report": {
    },
  • "reportId": "da0c66a4-9f37-4f9a-9988-0786ad301b17",
  • "reportName": "Report_2022-01-27T15-23+00Z_dryrun=true_a7456dd2-1acd-4bd9-8555-d44b2275a2da",
  • "type": "promotion"
}

Get a provisional rollback report

Get a provisional rollback report of changes when we rollback the configuration to the previous promotion.

Authorizations:
OAuth2
header Parameters
Accept-API-Version
required
string

protocol=1.0,resource=1.0

Responses

Response samples

Content type
application/json
{
  • "createdDate": "2022-01-27T15-23+00Z",
  • "dryRun": true,
  • "missingESVs": [
    ],
  • "previouslyIgnoredEncryptedSecrets": [
    ],
  • "promoter": "Barb Jensen",
  • "promotionDescription": "Promoting our Forgotten Username journey",
  • "promotionId": "da0c66a4-9f37-4f9a-9988-0786ad301b17",
  • "report": {
    },
  • "reportId": "da0c66a4-9f37-4f9a-9988-0786ad301b17",
  • "reportName": "Report_2022-01-27T15-23+00Z_dryrun=true_a7456dd2-1acd-4bd9-8555-d44b2275a2da",
  • "type": "promotion"
}

Get promotion reports

Get a list of previous promotion reports in date order.

Authorizations:
OAuth2
header Parameters
Accept-API-Version
required
string

protocol=1.0,resource=1.0

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Rollback a promotion

Rollback the most recent configuration promotion.

Authorizations:
OAuth2
header Parameters
Accept-API-Version
required
string

protocol=1.0,resource=1.0

Request Body schema: application/json
required

A request body with info required to initiate a rollback

promoter
string

The name of the admin user who initiated the promotion

promotionDescription
string

Promoter specified note to make it easier for them to identify what was promoted

unlockEnvironmentsAfterPromotion
boolean

A boolean denoting whether or not to automatically unlock the environments after a successful promotion

zendeskTicketReference
string

A string denoting the Zendesk ticket reference to be added to the promotion commit message

Responses

Request samples

Content type
application/json
{
  • "promoter": "string",
  • "promotionDescription": "string",
  • "unlockEnvironmentsAfterPromotion": true,
  • "zendeskTicketReference": "string"
}

Response samples

Content type
application/json
{
  • "result": "Rollback Complete"
}

Environment Configuration

Identity Cloud gives you the ability to configure various environment settings via REST.

Certificates

Operations related to certificates

Get all certificates

Returns all certificates installed in the tenant.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create certificate

Upload a new certificate to the tenant.

Authorizations:
OAuth2
Request Body schema: application/json
required

JSON body of the new certificate

active
boolean

The active status of the certificate. Set this to true for the certificate to actively be served.

certificate
required
string

The PEM formatted certificate.

privateKey
required
string

The private key for the certificate. For security reasons, only insert requests include this field.

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "certificate": "string",
  • "privateKey": "string"
}

Response samples

Content type
application/json
{
  • "active": true,
  • "certificate": "string",
  • "expireTime": "string",
  • "id": "string",
  • "issuer": "string",
  • "live": true,
  • "subject": "string",
  • "subjectAlternativeNames": [
    ],
  • "validFromTime": "string"
}

Delete certificate by ID

Deletes a certificate installed on the tenant. This certificate must be disabled before deletion will be allowed.

Authorizations:
OAuth2
path Parameters
id
required
string

ID of the certificate resource

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "string"
}

Get certificate by ID

Returns information about a certificate installed on the tenant.

Authorizations:
OAuth2
path Parameters
id
required
string

ID of the certificate resource

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "certificate": "string",
  • "expireTime": "string",
  • "id": "string",
  • "issuer": "string",
  • "live": true,
  • "subject": "string",
  • "subjectAlternativeNames": [
    ],
  • "validFromTime": "string"
}

Update certificate by ID

Updates information about a certificate installed on the tenant. This can be used to enable / disable certificates.

Authorizations:
OAuth2
path Parameters
id
required
string

ID of the certificate resource

Request Body schema: application/json
required

JSON body of the updated certificate

active
boolean

The active status of the certificate. Set this to true for the certificate to actively be served.

Responses

Request samples

Content type
application/json
{
  • "active": true
}

Response samples

Content type
application/json
{
  • "active": true,
  • "certificate": "string",
  • "expireTime": "string",
  • "id": "string",
  • "issuer": "string",
  • "live": true,
  • "subject": "string",
  • "subjectAlternativeNames": [
    ],
  • "validFromTime": "string"
}

CSRs

Operations related to certificate signing requests

Get all CSRs

Returns all certificate signing requests created in the environment

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create CSR

Create a new certificate signing request

Authorizations:
OAuth2
Request Body schema: application/json
required

JSON body of the new certificate signing request

algorithm
string
Default: "rsa"
Enum: "rsa" "ecdsa"

The algorithm for the private key. The encryption algorithm will either be RSA-2048 or ECDSA P-256 depending on the algorithm choice. The default is RSA-2048.

businessCategory
string

Category of business, such as "Private Organization", “Government Entity”, “Business Entity”, or “Non-Commercial Entity”. Relevant for EV certificates.

city
string
commonName
string

Domain name that the SSL certificate is securing

country
string[A-Z]{2}

Two-letter ISO-3166 country code

email
string^\S+@\S+$
jurisdictionCity
string

This field contains only information relevant to the Jurisdiction of Incorporation or Registration. Relevant for EV certificates.

jurisdictionCountry
string

This field contains only information relevant to the Jurisdiction of Incorporation or Registration. Relevant for EV certificates.

jurisdictionState
string

This field contains only information relevant to the Jurisdiction of Incorporation or Registration. Relevant for EV certificates.

organization
string

Full name of company

organizationalUnit
string

Company section or department

postalCode
string
serialNumber
string

The Registration (or similar) Number assigned to the Subject by the Incorporating or Registration Agency in its Jurisdiction of Incorporation or Registration. Relevant for EV certificates.

state
string
streetAddress
string
subjectAlternativeNames
Array of strings
Default: []

Additional domain or domains that the SSL certificate is securing

Responses

Request samples

Content type
application/json
{
  • "algorithm": "rsa",
  • "subjectAlternativeNames": [ ]
}

Response samples

Content type
application/json
{
  • "algorithm": "string",
  • "certificateID": "string",
  • "createdDate": "2006-01-02T15:04:05Z07:00",
  • "id": "string",
  • "request": "string",
  • "subject": "string",
  • "subjectAlternativeNames": [
    ]
}

Delete CSR by ID

Deletes a CSR created in the tenant.

Authorizations:
OAuth2
path Parameters
id
required
string

ID of the certificateSigningRequest

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "message": "unauthorized"
}

Get CSR by ID

Returns information about a CSR created in the tenant.

Authorizations:
OAuth2
path Parameters
id
required
string

ID of the CSR

Responses

Response samples

Content type
application/json
{
  • "algorithm": "string",
  • "certificateID": "string",
  • "createdDate": "2006-01-02T15:04:05Z07:00",
  • "id": "string",
  • "request": "string",
  • "subject": "string",
  • "subjectAlternativeNames": [
    ]
}

Update CSR by ID

Upload a certificate to complete a CSR request, installing the certificate in the tenant. Only the certificate field can be set on an upload request.

Authorizations:
OAuth2
path Parameters
id
required
string

ID of the certificateSigningRequest

Request Body schema: application/json
required

JSON body of the new certificate signing request

certificate
required
string

The matching signed certificate for the request. This should only be set on update requests to upload the certificate.

Responses

Request samples

Content type
application/json
{
  • "certificate": "string"
}

Response samples

Content type
application/json
{
  • "algorithm": "string",
  • "certificateID": "string",
  • "createdDate": "2006-01-02T15:04:05Z07:00",
  • "id": "string",
  • "request": "string",
  • "subject": "string",
  • "subjectAlternativeNames": [
    ]
}

Content Security Policy

Operations related to content security policy

Get enforced content security policy

Returns current enforced content security policy

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "directives": {
    }
}

Set enforced content security policy

Specify enforced content security policy

Authorizations:
OAuth2
Request Body schema: application/json
required

Enforced content security policy to apply to the tenant

active
boolean
object

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "directives": {
    }
}

Response samples

Content type
application/json
{
  • "active": true,
  • "directives": {
    }
}

Get report-only content security policy

Returns current report-only content security policy

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "active": true,
  • "directives": {
    }
}

Set report-only content security policy

Specify report-only content security policy

Authorizations:
OAuth2
Request Body schema: application/json
required

Enforced content security policy to apply to the tenant

active
boolean
object

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "directives": {
    }
}

Response samples

Content type
application/json
{
  • "active": true,
  • "directives": {
    }
}

Cookie Domains

Operations related to cookie domains

Get cookie domains

Returns current cookie domains

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "domains": [
    ]
}

Set cookie domains

Specify cookie domains

Authorizations:
OAuth2
Request Body schema: application/json
required

Cookie domains

domains
Array of strings

Cookie domains

Responses

Request samples

Content type
application/json
{
  • "domains": [
    ]
}

Response samples

Content type
application/json
{
  • "domains": [
    ]
}

Custom Domains

Operations related to custom domains

Verify a CNAME

Verify a CNAME

Authorizations:
OAuth2
query Parameters
_action
required
string
Value: "verify"

Requested action type

Request Body schema: application/json
required

Custom domain

name
required
string

The canonical name of the domain to be validated.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "code": 400,
  • "message": "string"
}

Get custom domains

Returns current custom domains

Authorizations:
OAuth2
path Parameters
realm
required
string
Enum: "alpha" "bravo"

Realm for the domain

Responses

Response samples

Content type
application/json
{
  • "domains": [
    ]
}

Set custom domains

Specify custom domains

Authorizations:
OAuth2
path Parameters
realm
required
string
Enum: "alpha" "bravo"

Realm for the domain

Request Body schema: application/json
required

Custom domains

domains
Array of strings

Custom domains

Responses

Request samples

Content type
application/json
{
  • "domains": [
    ]
}

Response samples

Content type
application/json
{
  • "domains": [
    ]
}

Federation Enforcement

Operations related to federation enforcement

Get enforcement of federation

Returns current federation enforcement settings

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "groups": "none"
}

Set enforcement of federation

Specify which admin groups are required to use federation

Authorizations:
OAuth2
Request Body schema: application/json
required

Enforcement settings to apply to the tenant

groups
required
string
Enum: "none" "non-global" "all"

Responses

Request samples

Content type
application/json
{
  • "groups": "none"
}

Response samples

Content type
application/json
{
  • "groups": "none"
}

Release

Operations related to release management

Get release information

Get release information

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "currentVersion": "string",
  • "nextUpgrade": "2019-08-24T14:15:22Z"
}

Get SSO cookie configuration

Returns current SSO cookie configuration

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "name": "string"
}

Reset SSO cookie configuration

Reset SSO cookie configuration to default

Authorizations:
OAuth2
query Parameters
_action
required
string
Value: "reset"

Reset SSO cookie configuration to default

Responses

Response samples

Content type
application/json
{
  • "name": "string"
}

Set SSO cookie configuration

Specify SSO cookie configuration

Authorizations:
OAuth2
Request Body schema: application/json
required

SSO cookie configuration to apply to the tenant

name
required
string^[a-zA-Z0-9]{1,32}$

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "name": "string"
}