Skip to main content
Star us on GitHub Star

Edge Management API Reference

API docs by Redocly

Ziti Edge Management (0.26.1)

Download OpenAPI specification:Download

OpenZiti: help@openziti.org URL: https://openziti.discourse.group License: Apache 2.0

OpenZiti Edge Management API

Informational

Returns version information

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Returns all capabilities this version of the controller is aware of, enabled or not.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Returns a list of API specs

Returns a list of spec files embedded within the controller for consumption/documentation/code geneartion

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Return a single spec resource

Returns single spec resource embedded within the controller for consumption/documentation/code geneartion

path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Returns the spec's file

Return the body of the specification (i.e. Swagger, OpenAPI 2.0, 3.0, etc).

path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
No sample

Returns a list of accessible resource counts

This endpoint is usefull for UIs that wish to display UI elements with counts.

Authorizations:
ztSession

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Returns version information

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Well Known

Get CA Cert Store

This endpoint is used during enrollments to bootstrap trust between enrolling clients and the Ziti Edge API. This endpoint returns a base64 encoded PKCS7 store. The content can be base64 decoded and parsed by any library that supports parsing PKCS7 stores.

Responses

API Session

List active API sessions

Returns a list of active API sessions. The resources can be sorted, filtered, and paginated. This endpoint requires admin access.

Authorizations:
ztSessionoauth2
query Parameters
limit
integer
offset
integer
filter
string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [
    ],
  • "meta": {
    }
}

Retrieves a single API Session

Retrieves a single API Session by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Deletes an API Sessions

Deletes and API sesion by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Auth Policy

List Auth Policies

Retrieves a list of Auth Policies

Authorizations:
ztSessionoauth2
query Parameters
limit
integer
offset
integer
filter
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Creates an Auth Policy

Creates an Auth Policy. Requires admin access.

Authorizations:
ztSession
Request Body schema: application/json

An Auth Policy to create

name
required
string
required
object (authPolicyPrimary)
required
object (authPolicySecondary)
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "primary": {
    },
  • "secondary": {
    },
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Retrieves a single Auth Policy

Retrieves a single Auth Policy by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Update all fields on an Auth Policy

Update all fields on an Auth Policy by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

An Auth Policy update object

name
required
string
required
object (authPolicyPrimary)
required
object (authPolicySecondary)
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "primary": {
    },
  • "secondary": {
    },
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Delete an Auth Policy

Delete an Auth Policy by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Update the supplied fields on an Auth Policy

Update only the supplied fields on an Auth Policy by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

An Auth Policy patch object

name
string or null
object (authPolicyPrimaryPatch)
object or null (authPolicySecondaryPatch)
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "primary": {
    },
  • "secondary": {
    },
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Authentication

Authenticate via a method supplied via a query string parameter

Allowed authentication methods include "password", "cert", and "ext-jwt"

query Parameters
method
required
string
Enum: "password" "cert" "ext-jwt"
Request Body schema: application/json
configTypes
Array of strings (configTypes)

Specific configuration types that should be returned

object (envInfo)

Environment information an authenticating client may provide

password
string (password) [ 5 .. 100 ] characters
object (sdkInfo)

SDK information an authenticating client may provide

username
string (username) [ 4 .. 100 ] characters

Responses

Request samples

Content type
application/json
{
  • "configTypes": [
    ],
  • "envInfo": {
    },
  • "password": "string",
  • "sdkInfo": {
    },
  • "username": "string"
}

Response samples

Content type
{
  • "data": {
    },
  • "meta": {
    }
}

Complete MFA authentication

Completes MFA authentication by submitting a MFA time based one time token or backup code.

Authorizations:
ztSessionoauth2
Request Body schema: application/json

An MFA validation request

code
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

MFA

Complete MFA authentication

Completes MFA authentication by submitting a MFA time based one time token or backup code.

Authorizations:
ztSessionoauth2
Request Body schema: application/json

An MFA validation request

code
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Returns the current status of MFA enrollment

Returns details about the current MFA enrollment. If enrollment has not been completed it will return the current MFA configuration details necessary to complete a POST /current-identity/mfa/verify.

Authorizations:
ztSessionoauth2

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Initiate MFA enrollment

Allows authenticator based MFA enrollment. If enrollment has already been completed, it must be disabled before attempting to re-enroll. Subsequent enrollment request is completed via POST /current-identity/mfa/verify

Authorizations:
ztSessionoauth2

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Disable MFA for the current identity

Disable MFA for the current identity. Requires a current valid time based one time password if MFA enrollment has been completed. If not, code should be an empty string. If one time passwords are not available and admin account can be used to remove MFA from the identity via DELETE /identities/<id>/mfa.

Authorizations:
ztSessionoauth2
header Parameters
mfa-validation-code
string

Responses

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Show a QR code for unverified MFA enrollments

Shows an QR code image for unverified MFA enrollments. 404s if the MFA enrollment has been completed or not started.

Authorizations:
ztSessionoauth2

Responses

For a completed MFA enrollment view the current recovery codes

Allows the viewing of recovery codes of an MFA enrollment. Requires a current valid time based one time password to interact with. Available after a completed MFA enrollment.

Authorizations:
ztSessionoauth2
header Parameters
mfa-validation-code
string
Request Body schema: application/json

An MFA validation request

code
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

For a completed MFA enrollment regenerate the recovery codes

Allows regeneration of recovery codes of an MFA enrollment. Requires a current valid time based one time password to interact with. Available after a completed MFA enrollment. This replaces all existing recovery codes.

Authorizations:
ztSessionoauth2
Request Body schema: application/json

An MFA validation request

code
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "error": {
    },
  • "meta": {
    }
}

Complete MFA enrollment by verifying a time based one time token

Completes MFA enrollment by accepting a time based one time password as verification. Called after MFA enrollment has been initiated via POST /current-identity/mfa.

Authorizations:
ztSessionoauth2
Request Body schema: application/json

An MFA validation request

code
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Remove MFA from an identitity

Allows an admin to remove MFA enrollment from a specific identity. Requires admin.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Authenticator

List authenticators

Returns a list of authenticators associated to identities. The resources can be sorted, filtered, and paginated. This endpoint requires admin access.

Authorizations:
ztSessionoauth2
query Parameters
limit
integer
offset
integer
filter
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Creates an authenticator

Creates an authenticator for a specific identity. Requires admin access.

Authorizations:
ztSession
Request Body schema: application/json

A Authenticator create object

certPem
string

The client certificate the identity will login with. Used only for method='cert'

identityId
required
string

The id of an existing identity that will be assigned this authenticator

method
required
string

The type of authenticator to create; which will dictate which properties on this object are required.

password
string

The password the identity will login with. Used only for method='updb'

object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

username
string

The username that the identity will login with. Used only for method='updb'

Responses

Request samples

Content type
application/json
{
  • "certPem": "string",
  • "identityId": "string",
  • "method": "string",
  • "password": "string",
  • "tags": {
    },
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "certPem": "string",
  • "identityId": "string",
  • "method": "string",
  • "password": "string",
  • "tags": {
    },
  • "username": "string"
}

Retrieves a single authenticator

Retrieves a single authenticator by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Update all fields on an authenticator

Update all fields on an authenticator by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

An authenticator put object

password
required
string (password) [ 5 .. 100 ] characters
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

username
required
string (username) [ 4 .. 100 ] characters

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "tags": {
    },
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Delete an Authenticator

Delete an authenticator by id. Deleting all authenticators for an identity will make it impossible to log in. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Update the supplied fields on an authenticator

Update the supplied fields on an authenticator by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

An authenticator patch object

password
string or null (passwordNullable) [ 5 .. 100 ] characters
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

username
string or null (usernameNullable) [ 4 .. 100 ] characters

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "tags": {
    },
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Reverts an authenticator to an enrollment

Allows an authenticator to be reverted to an enrollment and allows re-enrollment to occur. On success the created enrollment record response is provided and the source authenticator record will be deleted. The enrollment created depends on the authenticator. UPDB authenticators result in UPDB enrollments, CERT authenticators result in OTT enrollments, CERT + CA authenticators result in OTTCA enrollments.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

A reEnrollment request

expiresAt
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Certificate Authority

List CAs

Retrieves a list of CA resources; supports filtering, sorting, and pagination. Requires admin access.

Authorizations:
ztSessionoauth2
query Parameters
limit
integer
offset
integer
filter
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Creates a CA

Creates a CA in an unverified state. Requires admin access.

Authorizations:
ztSession
Request Body schema: application/json

A CA to create

certPem
required
string
object (externalIdClaim)
identityNameFormat
string
identityRoles
required
Array of strings (roles)
isAuthEnabled
required
boolean
isAutoCaEnrollmentEnabled
required
boolean
isOttCaEnrollmentEnabled
required
boolean
name
required
string
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

Responses

Request samples

Content type
application/json
{
  • "certPem": "-----BEGIN CERTIFICATE-----\nMIICUjCCAdmgAwIBAgIJANooo7NB+dZZMAoGCCqGSM49BAMCMF4xCzAJBgNVBAYT\nAlVTMQswCQYDVQQIDAJOQzETMBEGA1UECgwKTmV0Rm91bmRyeTEtMCsGA1UEAwwk\nTmV0Rm91bmRyeSBaaXRpIEV4dGVybmFsIEFQSSBSb290IENBMB4XDTE4MTExNTEy\nNTcwOVoXDTM4MTExMDEyNTcwOVowXjELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAk5D\nMRMwEQYDVQQKDApOZXRGb3VuZHJ5MS0wKwYDVQQDDCROZXRGb3VuZHJ5IFppdGkg\nRXh0ZXJuYWwgQVBJIFJvb3QgQ0EwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAARwq61Z\nIaqbaw0PDt3frJZaHjkxfZhwYrykI1GlbRNd/jix03lVG9qvpN5Og9fQfFFcFmD/\n3vCE9S6O0npm0mADQxcBcxbMRAH5dtBuCuiJW6qAAbPgiM32vqSxBiFt0KejYzBh\nMB0GA1UdDgQWBBRx1OVGuc/jdltDc8YBtkw8Tbr4fjAfBgNVHSMEGDAWgBRx1OVG\nuc/jdltDc8YBtkw8Tbr4fjAPBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIB\nhjAKBggqhkjOPQQDAgNnADBkAjBDRxNZUaIVpkQKnAgJukl3ysd3/i7Z6hDyIEms\nkllz/+ZvmdBp9iedV5o5BvJUggACMCv+UBFlJH7pmsOCo/F45Kk178YsCC7gaMxE\n1ZG1zveyMvsYsH04C9FndE6w2MLvlA==\n-----END CERTIFICATE-----\n",
  • "externalIdClaim": {
    },
  • "identityNameFormat": "string",
  • "identityRoles": [
    ],
  • "isAuthEnabled": true,
  • "isAutoCaEnrollmentEnabled": true,
  • "isOttCaEnrollmentEnabled": true,
  • "name": "Test 3rd Party External CA",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Retrieves a single CA

Retrieves a single CA by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Update all fields on a CA

Update all fields on a CA by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

A CA update object

object (externalIdClaim)
identityNameFormat
required
string
identityRoles
required
Array of strings (roles)
isAuthEnabled
required
boolean
isAutoCaEnrollmentEnabled
required
boolean
isOttCaEnrollmentEnabled
required
boolean
name
required
string
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

Responses

Request samples

Content type
application/json
{
  • "externalIdClaim": {
    },
  • "identityNameFormat": "string",
  • "identityRoles": [
    ],
  • "isAuthEnabled": true,
  • "isAutoCaEnrollmentEnabled": true,
  • "isOttCaEnrollmentEnabled": true,
  • "name": "My CA",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Delete a CA

Delete a CA by id. Deleting a CA will delete its associated certificate authenticators. This can make it impossible for identities to authenticate if they no longer have any valid authenticators. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Update the supplied fields on a CA

Update only the supplied fields on a CA by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

A CA patch object

object (externalIdClaimPatch)
identityNameFormat
string or null
identityRoles
Array of strings (roles)
isAuthEnabled
boolean or null
isAutoCaEnrollmentEnabled
boolean or null
isOttCaEnrollmentEnabled
boolean or null
name
string or null
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

Responses

Request samples

Content type
application/json
{
  • "externalIdClaim": {
    },
  • "identityNameFormat": "string",
  • "identityRoles": [
    ],
  • "isAuthEnabled": true,
  • "isAutoCaEnrollmentEnabled": true,
  • "isOttCaEnrollmentEnabled": true,
  • "name": "My CA",
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Retrieve the enrollment JWT for a CA

For CA auto enrollment, the enrollment JWT is static and provided on each CA resource. This endpoint provides the jwt as a text response.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/jwt
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbSI6ImNhIiwiaXNzIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6MTI 4MC8ifQ.Ot6lhNBSOw8ygHytdI5l7WDf9EWadOj44UPvJ0c-8mJ54fClWM3uMZrAHSSfV6KmOSZOeBBJe4VlNyoD-_MOECP0BzYSnSQP3E zJb0VlM-fFmGcKNGW157icyZNISfO43JL_Lw2QPBzTgikqSIj9eZnocC3BeAmZCHsVznnLfHWqDldcmuxnu-5MNOSrWV1x9iVcgLFlLHXK 2PLA4qIiZmlQTrQjpHJmUaoJ07mnj8hMKzxB3wBG8kpazjEo7HDRCO06aBH4eqFgf_l0iT8Dzcb31jquWMGUoSXPhf4lVJh_FiNcR1wVx- UiHLbG5h23Aqf1UJF-F38rc1FElKz0Zg

Verify a CA

Allows a CA to become verified by submitting a certificate in PEM format that has been signed by the target CA. The common name on the certificate must match the verificationToken property of the CA. Unverfieid CAs can not be used for enrollment/authentication. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Request Body schema: text/plain

A PEM formatted certificate signed by the target CA with the common name matching the CA's validationToken

string

Responses

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Config

List config-types

Retrieves a list of config-type resources; supports filtering, sorting, and pagination. Requires admin access.

Authorizations:
ztSessionoauth2
query Parameters
limit
integer
offset
integer
filter
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a config-type. Requires admin access.

Authorizations:
ztSession
Request Body schema: application/json

A config-type to create

name
required
string
object

A JSON schema to enforce configuration against

object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

Responses

Request samples

Content type
application/json
{
  • "name": "ziti-tunneler-server.v1",
  • "schema": { },
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Retrieves a single config-type

Retrieves a single config-type by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Update all fields on a config-type

Update all fields on a config-type by id. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

A config-type update object

name
required
string
object

A JSON schema to enforce configuration against

object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

Responses

Request samples

Content type
application/json
{
  • "name": "ziti-tunneler-server.v1",
  • "schema": { },
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Delete a config-type

Delete a config-type by id. Removing a configuration type that are in use will result in a 409 conflict HTTP status code and error. All configurations of a type must be removed first.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Update the supplied fields on a config-type

Update the supplied fields on a config-type. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

A config-type patch object

name
string
object

A JSON schema to enforce configuration against

object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

Responses

Request samples

Content type
application/json
{
  • "name": "ziti-tunneler-server.v1",
  • "schema": { },
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Lists the configs of a specific config-type

Lists the configs associated to a config-type. Requires admin access.

Authorizations:
ztSession
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

List configs

Retrieves a list of config resources; supports filtering, sorting, and pagination. Requires admin access.

Authorizations:
ztSessionoauth2
query Parameters
limit
integer
offset
integer
filter
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Create a config resource

Create a config resource. Requires admin access.

Authorizations:
ztSessionoauth2
Request Body schema: application/json

A config to create

configTypeId
required
string

The id of a config-type that the data section will match

required
object

Data payload is defined by the schema of the config-type defined in the type parameter

name
required
string
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

Responses

Request samples

Content type
application/json
{
  • "configTypeId": "cea49285-6c07-42cf-9f52-09a9b115c783",
  • "data": {
    },
  • "name": "test-config"
}

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Retrieves a single config

Retrieves a single config by id. Requires admin access.

Authorizations:
ztSessionoauth2
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Update all fields on a config

Update all fields on a config by id. Requires admin access.

Authorizations:
ztSessionoauth2
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

A config update object

required
object

Data payload is defined by the schema of the config-type defined in the type parameter

name
required
string
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "name": "example-config-name"
}

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Delete a config

Delete a config by id. Requires admin access.

Authorizations:
ztSessionoauth2
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Update the supplied fields on a config

Update the supplied fields on a config. Requires admin access.

Authorizations:
ztSessionoauth2
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

A config patch object

object

Data payload is defined by the schema of the config-type defined in the type parameter

name
string
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

Responses

Request samples

Content type
application/json
{
  • "data": {
    },
  • "name": "example-config-name"
}

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Current API Session

Return the current API session

Retrieves the API session that was used to issue the current request

Authorizations:
ztSessionoauth2

Responses

Response samples

Content type
{
  • "data": {
    },
  • "meta": {
    }
}

Logout

Terminates the current API session

Authorizations:
ztSessionoauth2

Responses

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

List authenticators for the current identity

Retrieves a list of authenticators assigned to the current API session's identity; supports filtering, sorting, and pagination.

Authorizations:
ztSessionoauth2
query Parameters
limit
integer
offset
integer
filter
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    }
}

Retrieve an authenticator for the current identity

Retrieves a single authenticator by id. Will only show authenticators assigned to the API session's identity.

Authorizations:
ztSessionoauth2
path Parameters
id
required
string

The id of the requested resource

Responses

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Update all fields on an authenticator of this identity

Update all fields on an authenticator by id. Will only update authenticators assigned to the API session's identity.

Authorizations:
ztSessionoauth2
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

An authenticator put object

password
required
string (password) [ 5 .. 100 ] characters
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

username
required
string (username) [ 4 .. 100 ] characters
currentPassword
required
string (password) [ 5 .. 100 ] characters

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "tags": {
    },
  • "username": "string",
  • "currentPassword": "string"
}

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Update the supplied fields on an authenticator of this identity

Update the supplied fields on an authenticator by id. Will only update authenticators assigned to the API session's identity.

Authorizations:
ztSessionoauth2
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json

An authenticator patch object

password
string or null (passwordNullable) [ 5 .. 100 ] characters
object or null (tags)

A map of user defined fields and values. The values are limited to the following types/values: null, string, boolean

username
string or null (usernameNullable) [ 4 .. 100 ] characters
currentPassword
required
string (password) [ 5 .. 100 ] characters

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "tags": {
    },
  • "username": "string",
  • "currentPassword": "string"
}

Response samples

Content type
application/json
{
  • "data": { },
  • "meta": {
    }
}

Allows the current identity to recieve a new certificate associated with a certificate based authenticator

This endpoint only functions for certificates issued by the controller. 3rd party certificates are not handled. Allows an identity to extend its certificate's expiration date by using its current and valid client certificate to submit a CSR. This CSR may be passed in using a new private key, thus allowing private key rotation. The response from this endpoint is a new client certificate which the client must be verified via the /authenticators/{id}/extend-verify endpoint. After verification is completion any new connections must be made with new certificate. Prior to verification the old client certificate remains active.

Authorizations:
ztSessionoauth2
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
clientCertCsr
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "data": {
    },
  • "meta": {
    }
}

Allows the current identity to validate reciept of a new client certificate

After submitting a CSR for a new client certificate the resulting public certificate must be re-submitted to this endpoint to verify receipt. After receipt, the new client certificate must be used for new authentication requests.

Authorizations:
ztSessionoauth2
path Parameters
id
required
string

The id of the requested resource

Request Body schema: application/json
clientCert
required
string

A PEM encoded client certificate previously returned after an extension request

Responses

Request samples

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

Response samples

Content type
application/json