Skip to main content
API docs by Redocly

AST Services (3.0.3)

Download OpenAPI specification:Download

License: Commercial

Certificate Authority

Get signer with certificate Deprecated

Returns the signer for the tenant including the certificate, if already signed

This operation requires Admin read privileges.

Deprecation

This endpoint has been obsoleted by the transition to allowing multiple signers per tenant, which is now used to facilitate signer key rotation. Please use GET /v2/tenants/{tenant}/signers/current for equivalent behavior.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

Responses

Response samples

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

Trigger signer CA creation Deprecated

Trigger creation of a signer key pair and certificate.

This operation requires Admin write privileges.

Deprecation

This endpoint has been obsoleted by the transition to allowing multiple signers per tenant, which is now used to facilitate signer key rotation. Please use POST /v2/tenants/{tenant}/signers for equivalent behavior.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

Request Body schema: application/json
required

Contains the signer's name

name
required
string non-empty

The signer's name

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "tenant": "master",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "generation": 0,
  • "state": "ACTIVE"
}

Reissue Signer Certificate Deprecated

Allows to reissue the signer for the tenant. The old key is reused for the new certificate.

This operation requires Admin write privileges.

Deprecation

This endpoint has been obsoleted by the transition to allowing multiple signers per tenant, which is now used to facilitate signer key rotation. Please use POST /v2/tenants/{tenant}/signers/current/renew for equivalent behavior.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

Request Body schema: application/json
optional
ignoreNotIssued
boolean
Default: false

If set to false (the default), the request will fail if the signer CA was not yet issued.

When setting this to true, the request will only fail, if there is a CSR for that signer currently enqueued. If the CA was already issued or the issuance failed, the a new CSR will be enqueued.

Responses

Request samples

Content type
application/json
{
  • "ignoreNotIssued": false
}

Response samples

Content type
application/json
{
  • "id": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "tenant": "master",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "generation": 0,
  • "state": "ACTIVE"
}

Delete signer Deprecated

Allows deleting the signer for the tenant. This can only be done if there are no certificates depending on that signer. As soon as a user or gateway certificate has been requested using that signer, deletion is no longer possible.

This method may be used to remove a signer for which the CA creation failed. It is RECOMMENDED to only run this operation after checking that the signer certificate is ISSUED or FAILED. This can be done by GET /v1/tenants/{tenantId}/certificates/admin/{signerId}.

This operation requires Admin write privileges.

Deprecation

This endpoint has been obsoleted by the transition to allowing multiple signers per tenant, which is now used to facilitate signer key rotation. Please use DELETE /v2/tenants/{tenant}/signers/current for equivalent behavior.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

List existing tenant signers

Returns signers for the tenant as a paginated list. The page number and page size can be selected using the page and page_size parameters, respectively.

The list may be filtered using a custom filter string. See the parameter schema below for a detailed description.

Authorization

This endpoint requires admin read privileges.

Authorizations:
BearerAuth
path Parameters
tenant
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

query Parameters
page
integer <int32> >= 1
Default: 1

The page number (1-based)

page_size
integer <int32> [ 5 .. 100 ]
Default: 20

The number of entries per page, must be between 5 and 100

filter
string

Filter for specific properties of a signer.

A filter is a string of the format <property name><ws?><operator><ws?><value><ws?><flags?> where <ws?> denotes optional whitespace. You can also arrange several conditions using <ws+><logicalOperator><ws+>. To change the priority of logical operators, you can use several nested <bracket>

<property name> is one of the following properties of a property of signers:

  • name
  • id
  • createdAt
  • updatedAt
  • generation
  • state

<operator> can be one of the following operators known from CSS attribute selectors:

  • = - is equal to
  • != - is not equal to
  • <> - is not equal to
  • ^= - starts with
  • $= - ends with
  • *= - contains
  • > - greater than
  • >= - greater than or equal to
  • < - less than
  • <= - less than or equal to
  • like - sql like(_ - any one character, % - zero, one or multiple characters)
  • in - equal to any value in a list
  • !in - not equal to all values in a list

There are special operators in and !in to test set membership/non-membership. The can be used with a comma-separated list of values enclosed in curly braces, such as <property name> in {value1, value2, "quoted value"}.

<value> is a string consisting of a-z, A-Z, 0-9, -, _, %, . or '<any character except to \'>', `<any character except to \`>`, "<any character except to \">" null is a reserved name expressing a null value.

<flags> is an optionally joined list of characters enclosed in square braces and may contain the following flags:

  • [i] | [I] - perform all matching case-insensitive

<logicalOperator> can be one of several aliases for or and and operators:

  • or | OR | || - logical or operator
  • and | AND | && - logical and operator

<bracket> - can be one of:

  • ( - left bracket
  • ) - right bracket

Examples:

  • name^=SignerA- selects all signers whose names begin with SignerA- (case-sensitive)
  • name ^= SignerA- [i] selects all signers whose names begin with SignerA- (case-insensitive). name^=SignerA-[i] is an equivalent representation.
  • name="" selects all signers whose names are empty
  • (name="test t" && id=a1) or (id*=b and name*='kate r') select all entities where name = "test t" and id = "a1" or where name contains "kate r" and id contains "b"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new tenant signer

Creates a new signer for the tenant.

This endpoint may be used to create a signer for the first time, i.e. when there are no other signers for the same tenant. In this case, a fresh ACTIVE signer is created and enqueued for certificate issuance.

If there's already a signer for the tenant, this endpoint triggers the creation of a new signer, which will become the ACTIVE signer for the tenant. For the new signer, a fresh key pair is generated according to the current signer key generation settings in the service configuration. The previous ACTIVE signer of the tenant is transitioned into state RETIRED, where it can still be used for certificate path validation, but no longer for creating signatures.

Authorization

This endpoint requires admin write privileges.

Authorizations:
BearerAuth
path Parameters
tenant
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

Request Body schema: application/json
optional
name
string non-empty

A readable name for the signer. Can be omitted to use the configured default naming schema

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "tenant": "master",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "generation": 0,
  • "state": "ACTIVE"
}

Get the specified tenant signer including the certificate

This endpoint returns the specified signer for the tenant.

The signerSpec may be a Signer ID in the ULID format. In that case, the signer with the given ID is returned if it belongs to the specified tenant.

Alternatively, signerSpec may be current, which returns the latest ACTIVE signer for the tenant. If there is no such signer, 404 is returned.

Authorization

This operation can be executed with admin read or AST Client privileges.

Authorizations:
BearerAuth
path Parameters
tenant
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

required
Id (string) or string

The signer specification. Can be either the signer ID, or the literal string current.

The special value current refers to the most recently created signer in ACTIVE state.

Responses

Response samples

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

Delete the specified tenant signer and its certificate

This endpoint deletes the specified signer. Note that this is only possible if the signer CA wasn't used yet to issue any certificate. If certificates have already been issued by the signer, it can only be retired (replaced) or revoked. Revoking a signer is possible via POST /v2/tenants/{tenant}/signers/{signerSpec}/revoke. This makes sure that the signer can be used neither to issue a certificate, nor to perform certificate path validation. The signer can be replaced via POST /v2/tenants/{tenant}/signers, which will create a new signer for the tenant that will be used to issue certificates in the future. The old signer remains available for certificate path validation.

The signerSpec may be a Signer ID in the ULID format. In that case, the signer with the given ID is returned if it belongs to the specified tenant.

Authorization

This endpoint requires admin write privileges.

Authorizations:
BearerAuth
path Parameters
tenant
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

required
Id (string) or string

The signer specification. Can be either the signer ID, or the literal string current.

The special value current refers to the most recently created signer in ACTIVE state.

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Get the full chain for the specified tenant signer

This endpoint returns the certificate chain of the specified signer for the tenant. This operation can only be called if the signer's certificate was already issued, otherwise an error will be returned.

The signerSpec may be a Signer ID in the ULID format. In that case, the chain for the signer with the given ID is returned if it belongs to the specified tenant.

Alternatively, signerSpec may be current, which returns the chain for the latest ACTIVE signer for the tenant. If there is no such signer, 404 is returned.

Authorization

This operation can be executed with admin read or AST Client privileges.

Authorizations:
BearerAuth
path Parameters
tenant
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

required
Id (string) or string

The signer specification. Can be either the signer ID, or the literal string current.

The special value current refers to the most recently created signer in ACTIVE state.

Responses

Response samples

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

Renew the specified tenant signer's certificate

Allows to renew the signer CA for the tenant. The old key is reused for the new certificate.

This endpoint can be called to keep the certificate for a certain signer alive when it is close to expiry. Additionally, it must be called after the Issuer CA has been changed to a certificate with a different key than before.

The signerSpec may be a Signer ID in the ULID format. In that case, the signer with the given ID is enqueued for certificate renewal.

Alternatively, signerSpec may be current, which renews the latest ACTIVE signer for the tenant. If there is no such signer, 404 is returned.

Authorization

This endpoint requires Admin write privileges.

Authorizations:
BearerAuth
path Parameters
tenant
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

required
Id (string) or string

The signer specification. Can be either the signer ID, or the literal string current.

The special value current refers to the most recently created signer in ACTIVE state.

Request Body schema: application/json
optional
ignoreNotIssued
boolean
Default: false

If set to false (the default), the request will fail if the signer CA was not yet issued.

When setting this to true, the request will only fail, if there is a CSR for that signer currently enqueued. If the CA was already issued or the issuance failed, the a new CSR will be enqueued.

Responses

Request samples

Content type
application/json
{
  • "ignoreNotIssued": false
}

Response samples

Content type
application/json
{
  • "id": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "tenant": "master",
  • "name": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "generation": 0,
  • "state": "ACTIVE"
}

Revoke the specified tenant signer's certificate

Revokes a specific signer's certificate. After this operation completes, the certificate of the signer is erased from the database and the signer can't be used anymore for certificate path validation or signature validation.

This endpoint can be called in the event of key compromise or when an old (probably RETIRED signer certificate) needs to be disabled due to security policies.

The signerSpec may be a Signer ID in the ULID format. In that case, the signer with the given ID is enqueued for certificate renewal.

Alternatively, signerSpec may be current, which renews the latest ACTIVE signer for the tenant. If there is no such signer, 404 is returned.

Authorization

This endpoint required admin write privileges.

Authorizations:
BearerAuth
path Parameters
tenant
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

required
Id (string) or string

The signer specification. Can be either the signer ID, or the literal string current.

The special value current refers to the most recently created signer in ACTIVE state.

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Get a paginated list of certificates

Returns a paginated list of certificate information.

This operation requires Admin read privileges.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

query Parameters
page
integer <int32> >= 1
Default: 1

The page number (1-based)

page_size
integer <int32> [ 5 .. 100 ]
Default: 20

The number of entries per page, must be between 5 and 100

filter
string

Filter for specific properties of a certificate.

A filter is a string of the format <property name><ws?><operator><ws?><value><ws?><flags?> where <ws?> denotes optional whitespace. You can also arrange several conditions using <ws+><logicalOperator><ws+>. To change the priority of logical operators, you can use several nested <bracket>

<property name> is one of the following properties of certificates:

  • certRef
  • status
  • user
  • client
  • profile

<operator> can be one of the following operators known from CSS attribute selectors:

  • = - is equal to
  • != - is not equal to
  • <> - is not equal to
  • ^= - starts with
  • $= - ends with
  • *= - contains
  • > - greater than
  • >= - greater than or equal to
  • < - less than
  • <= - less than or equal to
  • like - sql like(_ - any one character, % - zero, one or multiple characters)
  • in - equal to any value in a list
  • !in - not equal to all values in a list

There are special operators in and !in to test set membership/non-membership. The can be used with a comma-separated list of values enclosed in curly braces, such as <property name> in {value1, value2, "quoted value"}.

<value> is a string consisting of a-z, A-Z, 0-9, -, _, %, . or '<any character except to \'>', `<any character except to \`>`, "<any character except to \">" null is a reserved name expressing a null value.

<flags> is an optionally joined list of characters enclosed in square braces and may contain the following flags:

  • [i] | [I] - perform all matching case-insensitive

<logicalOperator> can be one of several aliases for or and and operators:

  • or | OR | || - logical or operator
  • and | AND | && - logical and operator

<bracket> - can be one of:

  • ( - left bracket
  • ) - right bracket

Examples:

  • user=cb9f4b9c-5ebd-44e0-a9c6-806ef49483c1 selects all certificate requested by user cb9f4b9c-5ebd-44e0-a9c6-806ef49483c1` (case-sensitive)
  • profile in { AST_DEVICE, SIGNATURE } selects all certificates with a the AST_DEVICE or SIGNATURE profile
  • profile !in { AST_DEVICE, SIGNATURE } selects all certificates with a different profile from AST_DEVICE or SIGNATURE

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Check the status of a certificate request

Checks the status of a previously filed certificate request. If the request reference refers to a known request, the status will be returned. Otherwise, 404 is raised.

This operation requires Admin read privileges.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

certRef
required
string (Id) ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

The request reference obtained when requesting the certificate

Responses

Response samples

Content type
application/json
{
  • "certRef": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "status": "REQUESTED",
  • "signer": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "user": "string",
  • "client": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "requestedAt": "2019-08-24T14:15:22Z",
  • "issuedAt": "2019-08-24T14:15:22Z",
  • "certProfile": "AST_DEVICE"
}

Create signed SDK Config

Creates signed SDK Config

Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The tenant name (equal to the realm name in IDP)

Request Body schema: application/json
required
required
Array of Base64 (string) or Base64Url (string) [ 1 .. 50 ] items

A list of trusted X.509 TLS certificates in base64 or base64url encoding.

astUrl
string <= 256 characters ^https?://[-a-zA-Z0-9+&@#/%?=~_|!:,.;]*[-a-zA...

The AST gateway URL

Array of objects (ServiceEntry) [ 0 .. 50 ] items

A list of AST services with their respective URLs

Responses

Request samples

Content type
application/json
{
  • "tlsBundle": [
    ],
  • "astUrl": "string",
  • "services": []
}

Response samples

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

Client Management

Get overview information about all linked ASTClients for a given userId and tenantId

Get overview information about all linked ASTClients for a given userId and tenantId. List can be filtered.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

An unique Id of a tenant

query Parameters
userId
required
string [ 3 .. 255 ] characters
Example: userId=123e4567-e89b-12d3-a456-42665544a3f7

An unique Id of a User

filter
Array of strings[ items[a-zA-Z]+\s*(=|\!=|\^=|\$=|\*=)\s*(""|[a-zA-Z... ]

Filter for specific client.

This parameter is repeatable and multiple filters will be applied using logical AND.

A filter is a string of the form <field><ws?><operator><ws?><value><ws?><flags?> where <ws?> denotes optional whitespace.

<field> one of the field of AST Client specified below:

  • appName
  • astClientId
  • appPlatform
  • sdkVersion
  • appVersion
  • lockState - the value of it can be one of the following: NONE, LOCKED, UNLOCKED

<operator> can be one of the following operators known from CSS attribute selectors:

  • = - is equal to
  • != - is not equal to
  • <> - is not equal to
  • ^= - starts with
  • $= - ends with
  • *= - contains
  • > - greater than
  • >= - greater than or equal to
  • < - less than
  • <= - less than or equal to
  • like - sql like(_ - any one character, % - zero, one or multiple characters)
  • in - equal to any value in a list
  • !in - not equal to all values in a list

<value> is a string consisting of a-z, A-Z, 0-9, - and _ or '<any character except to \'>', `<any character except to \`>`, "<any character except to \">"

  • null | NULL without any quotes could be used only with = and != operators. It used to check entity for null value

<flags> is an optionally joined list of characters enclosed in square braces and may contain the following flags:

  • [i] | [I] - perform all matching case-insensitive

<logicalOperator> can be one of several aliases for or and and operators:

  • or | OR | || - logical or operator
  • and | AND | && - logical and operator

<bracket> - can be one of:

  • ( - left bracket
  • ) - right bracket

Examples:

  • name^=EntityA- selects all entities whose names begin with EntityA- (case-sensitive)
  • name ^= EntityA- [i] selects all entities whose names begin with EntityA- (case-insensitive). name^=EntityA-[i] is an equivalent representation
  • name="" selects all entities whose names are empty
  • (name="test t" && id=a1) or (id*=b and name*='kate r') select all entities where the name = "test t" and id = "a1" or where name contains "kate r" and id contains "b"
  • name=null select all entities where the name is null
  • name like "_ntony %" select all entities where the name starts with any one character, continues with ntony and ends with any string. For Example Antony Jakson
  • name > mike[i] select all entities where the name greater than mike by characters(case-insensitive)
  • id >= 5 select all entities where the id >= 5
  • name in {Mike, Rafael} select all entities where the name equal Mike or Rafael
  • name !in {'addison monroe', 'briley brinkley'} [i] select all entities where the name not equal Addison Monroe and Briley Brinkley (case-insensitive)
  • id <= 345.456 select all entities where the id <= 345.456
  • id in { 4, 5, 3.2 } select all entities where the id equal 4, 5 or 3.2

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a list of userIds for the linked ASTClient

Get a list of userIds linked to ASTClient for the specified astClientId and tenantId

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

An unique Id of a tenant

query Parameters
astClientId
required
string^([0-9A-HJKMNP-TV-Z]{26})$
Example: astClientId=01FH8MDGN9W5C3RXRFNX6G164S

An unique Id of a ASTClient in ULID-like format

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Lock client

Lock client's ability to perform a login operation (for the specified tenantId)

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

An unique Id of a tenant

Request Body schema: application/json
required
astClientId
required
string^([0-9A-HJKMNP-TV-Z]{26})$

An unique Id of a ASTClient in ULID-like format

lockReason
required
string

Responses

Request samples

Content type
application/json
{
  • "astClientId": "01FH8MDGN9W5C3RXRFNX6G164S",
  • "lockReason": "Locked by admin"
}

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Unlock client

Unlock client's ability to perform a login operation (by astClientId for the specified tenantId)

Authorizations:
BearerAuth
path Parameters
astClientId
required
string^([0-9A-HJKMNP-TV-Z]{26})$
Example: 01FH8MDGN9W5C3RXRFNX6G164S

An unique Id of a ASTClient in ULID-like format

tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

An unique Id of a tenant

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Unlink user Deprecated

Removes the link between the selected user and ASTClient for the specified tenantId

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

An unique Id of a tenant

Request Body schema: application/json
required
userId
required
string [ 3 .. 255 ] characters

An unique Id of a User

astClientId
required
string^([0-9A-HJKMNP-TV-Z]{26})$

An unique Id of a ASTClient in ULID-like format

Responses

Request samples

Content type
application/json
{
  • "userId": "123e4567-e89b-12d3-a456-42665544a3f7",
  • "astClientId": "01FH8MDGN9W5C3RXRFNX6G164S"
}

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Delete client

Delete client by astClientId for the specified tenantId.

IMPORTANT: Before deleting a client, all existing links must be removed.

See GET /v1/tenants/{tenantId}/users to find linked users.

See POST/v1/tenants/{tenantId}/unlink to unlink users.

Authorizations:
BearerAuth
path Parameters
astClientId
required
string^([0-9A-HJKMNP-TV-Z]{26})$
Example: 01FH8MDGN9W5C3RXRFNX6G164S

An unique Id of a ASTClient in ULID-like format

tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

An unique Id of a tenant

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Delete user data

Delete all user-related resources - clients(if they are not related to any other users), locales, links, etc.

Authorizations:
BearerAuth
path Parameters
userId
required
string [ 3 .. 255 ] characters
Example: 123e4567-e89b-12d3-a456-42665544a3f7

An unique Id of a User

tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

An unique Id of a tenant

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Detailed information about a selected ASTClient

Get detailed information about ASTClient by astClientId for the specified tenantId

Authorizations:
BearerAuth
path Parameters
astClientId
required
string^([0-9A-HJKMNP-TV-Z]{26})$
Example: 01FH8MDGN9W5C3RXRFNX6G164S

An unique Id of a ASTClient in ULID-like format

tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

An unique Id of a tenant

Responses

Response samples

Content type
application/json
{
  • "astClientId": "01FH8MDGN9W5C3RXRFNX6G164S",
  • "appVersion": "0.0.1-pythondemo",
  • "risks": "beep-boop",
  • "lockState": "NONE",
  • "createdOn": 1632819559770,
  • "linkedOnOrMloaUpdated": 1632819559770,
  • "lastSuccessfulVerification": 1632819559770,
  • "lastFailedVerification": 1632819559770,
  • "clientDevice": "Huawei",
  • "clientOsVersion": "1.0.0",
  • "sdkVersion": "0.0.1-test",
  • "deviceName": "Laptop-333",
  • "lockReason": "Locked due incorrect password",
  • "riskAnalysis": {
    }
}

Force disconnect all clients belong to the user

Immediately disconnect user's clients. It will be processed without order and exists events can be lost. If a body of the request is omitted, then it disconnects ALL user's clients.

Here is the list of available actions (see the specification of a body of the request below):

  • ALL_CLIENTS - disconnect all user's clients
  • SPECIFIED_CLIENTS - disconnect the specified clients
  • ALL_EXCEPT_SPECIFIED_CLIENTS - disconnect all except the specified clients
Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

An unique Id of a tenant

userId
required
string [ 3 .. 255 ] characters
Example: 123e4567-e89b-12d3-a456-42665544a3f7

An unique Id of a User

Request Body schema: application/json
disconnectType
string
Default: "ALL_CLIENTS"
Enum: "ALL_CLIENTS" "SPECIFIED_CLIENTS" "ALL_EXCEPT_SPECIFIED_CLIENTS"

The disconnect action type.

clientIds
Array of strings[ items^([0-9A-HJKMNP-TV-Z]{26})$ ]

The list of client IDs. Required for SPECIFIED_CLIENTS and ALL_EXCEPT_SPECIFIED_CLIENTS actions.

Responses

Request samples

Content type
application/json
{
  • "disconnectType": "SPECIFIED_CLIENTS",
  • "clientIds": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Unlink user's clients

Unlink user's clients. If a body of the request is omitted, then it unlinks ALL user's clients.

Here is the list of available actions (see the specification of a body of the request below):

  • ALL_CLIENTS - unlink all user's clients
  • SPECIFIED_CLIENTS - unlink the specified clients
  • ALL_EXCEPT_SPECIFIED_CLIENTS - unlink all except the specified clients
Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

An unique Id of a tenant

userId
required
string [ 3 .. 255 ] characters
Example: 123e4567-e89b-12d3-a456-42665544a3f7

An unique Id of a User

Request Body schema: application/json
unlinkType
string
Default: "ALL_CLIENTS"
Enum: "ALL_CLIENTS" "SPECIFIED_CLIENTS" "ALL_EXCEPT_SPECIFIED_CLIENTS"

The unlink action type.

clientIds
Array of strings[ items^([0-9A-HJKMNP-TV-Z]{26})$ ]

The list of client IDs. Required for SPECIFIED_CLIENTS and ALL_EXCEPT_SPECIFIED_CLIENTS actions.

Responses

Request samples

Content type
application/json
{
  • "unlinkType": "SPECIFIED_CLIENTS",
  • "clientIds": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Get runtime configuration of AST Login for the given tenant

Get runtime configuration of AST Login for the given tenant

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

An unique Id of a tenant

Responses

Response samples

Content type
application/json
{
  • "risks": {
    }
}

Update runtime configuration of AST Login for the given tenant

Update runtime configuration of AST Login for the given tenant

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

An unique Id of a tenant

Request Body schema: application/json
required
required
object
enableInference
required
boolean

Responses

Request samples

Content type
application/json
{
  • "risks": {
    }
}

Response samples

Content type
application/json
{
  • "risks": {
    }
}

Client Properties

List all properties for user

Get list of all properties without astClientId for specified userId.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

The id of the tenant

userId
required
string [ 3 .. 255 ] characters
Example: 1ZN1FP8NRQ8NHB7Z1CJRZPDBX3

The id of the user

query Parameters
page
integer <int32> >= 1
Default: 1

The page number (1-based)

page_size
integer <int32> [ 5 .. 100 ]
Default: 20

The number of entries per page, must be between 5 and 100

filter
Array of strings[ items[a-zA-Z]+\s*(=|\!=|\^=|\$=|\*=)\s*(""|[a-zA-Z... ]

Filter for specific properties.

This parameter is repeatable and multiple filters will be applied using logical AND.

A filter is a string of the form <property name><ws?><operator><ws?><value><ws?><flags?> where <ws?> denotes optional whitespace. You can also arrange several conditions using <ws+><logicalOperator><ws+>. To change the priority of logical operators, you can use several nested <bracket>

<property name> is the name of a Property field of AST Client:

  • name
  • id
  • value

<operator> can be one of the following operators known from CSS attribute selectors:

  • = - is equal to
  • != - is not equal to
  • <> - is not equal to
  • ^= - starts with
  • $= - ends with
  • *= - contains
  • > - greater than
  • >= - greater than or equal to
  • < - less than
  • <= - less than or equal to
  • like - sql like(_ - any one character, % - zero, one or multiple characters)
  • in - equal to any value in a list
  • !in - not equal to all values in a list

<value> is a string consisting of a-z, A-Z, 0-9, -, _, % or '<any character except single quote(')>', `<any character except back quote(`)>`, "<any character except double quotes(")>"

  • null | NULL without any quotes could be used with = and != operators to check entity for null value

<flags> is an optional joined list of characters enclosed in square braces and may contain the following flags:

  • [i] | [I] - perform all matching case-insensitive

<logicalOperator> can be one of several aliases for or and and operators:

  • or | OR | || - logical or operator
  • and | AND | && - logical and operator

<bracket> - can be one of:

  • ( - left bracket
  • ) - right bracket

Examples:

  • name^=EntityA- selects all entities whose names begin with EntityA- (case-sensitive)
  • name ^= EntityA- [i] selects all entities whose names begin with EntityA- (case-insensitive). name^=EntityA-[i] is an equivalent representation
  • name="" selects all entities whose names are empty
  • (name="test t" && id=a1) or (id*=b and name*='kate r') select all entities where the name = "test t" and id = "a1" or where name contains "kate r" and id contains "b"
  • name=null select all entities where the name is null
  • name like "_ntony %" select all entities where the name starts with any one character, continues with ntony and ends with any string. For Example Antony Jakson
  • name > mike[i] select all entities where the name greater than mike by characters(case-insensitive)
  • id >= 5 select all entities where the id >= 5
  • name in {Mike, Rafael} select all entities where the name equal Mike or Rafael
  • name !in {'addison monroe', 'briley brinkley'} [i] select all entities where the name not equal Addison Monroe and Briley Brinkley (case-insensitive)
  • id <= 345.456 select all entities where the id <= 345.456
  • id in { 4, 5, 3.2 } select all entities where the id equal 4, 5 or 3.2

Error could be UnknownProperty(if were added properties names for validation, or was not found compatible field extractor) or ParsingError(if some error was found in filter syntax)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List all properties for user and AST Client

Get list of all properties for specified userId and astClientId.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

The id of the tenant

userId
required
string [ 3 .. 255 ] characters
Example: 1ZN1FP8NRQ8NHB7Z1CJRZPDBX3

The id of the user

astClientId
required
string^([0-9A-HJKMNP-TV-Z]{26})$
Example: 1ZN1FP8NRQ8NHB7Z1CJRZPDBX5

The id of the AST Client

query Parameters
page
integer <int32> >= 1
Default: 1

The page number (1-based)

page_size
integer <int32> [ 5 .. 100 ]
Default: 20

The number of entries per page, must be between 5 and 100

filter
Array of strings[ items[a-zA-Z]+\s*(=|\!=|\^=|\$=|\*=)\s*(""|[a-zA-Z... ]

Filter for specific properties.

This parameter is repeatable and multiple filters will be applied using logical AND.

A filter is a string of the form <property name><ws?><operator><ws?><value><ws?><flags?> where <ws?> denotes optional whitespace. You can also arrange several conditions using <ws+><logicalOperator><ws+>. To change the priority of logical operators, you can use several nested <bracket>

<property name> is the name of a Property field of AST Client:

  • name
  • id
  • value

<operator> can be one of the following operators known from CSS attribute selectors:

  • = - is equal to
  • != - is not equal to
  • <> - is not equal to
  • ^= - starts with
  • $= - ends with
  • *= - contains
  • > - greater than
  • >= - greater than or equal to
  • < - less than
  • <= - less than or equal to
  • like - sql like(_ - any one character, % - zero, one or multiple characters)
  • in - equal to any value in a list
  • !in - not equal to all values in a list

<value> is a string consisting of a-z, A-Z, 0-9, -, _, % or '<any character except single quote(')>', `<any character except back quote(`)>`, "<any character except double quotes(")>"

  • null | NULL without any quotes could be used with = and != operators to check entity for null value

<flags> is an optional joined list of characters enclosed in square braces and may contain the following flags:

  • [i] | [I] - perform all matching case-insensitive

<logicalOperator> can be one of several aliases for or and and operators:

  • or | OR | || - logical or operator
  • and | AND | && - logical and operator

<bracket> - can be one of:

  • ( - left bracket
  • ) - right bracket

Examples:

  • name^=EntityA- selects all entities whose names begin with EntityA- (case-sensitive)
  • name ^= EntityA- [i] selects all entities whose names begin with EntityA- (case-insensitive). name^=EntityA-[i] is an equivalent representation
  • name="" selects all entities whose names are empty
  • (name="test t" && id=a1) or (id*=b and name*='kate r') select all entities where the name = "test t" and id = "a1" or where name contains "kate r" and id contains "b"
  • name=null select all entities where the name is null
  • name like "_ntony %" select all entities where the name starts with any one character, continues with ntony and ends with any string. For Example Antony Jakson
  • name > mike[i] select all entities where the name greater than mike by characters(case-insensitive)
  • id >= 5 select all entities where the id >= 5
  • name in {Mike, Rafael} select all entities where the name equal Mike or Rafael
  • name !in {'addison monroe', 'briley brinkley'} [i] select all entities where the name not equal Addison Monroe and Briley Brinkley (case-insensitive)
  • id <= 345.456 select all entities where the id <= 345.456
  • id in { 4, 5, 3.2 } select all entities where the id equal 4, 5 or 3.2

Error could be UnknownProperty(if were added properties names for validation, or was not found compatible field extractor) or ParsingError(if some error was found in filter syntax)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a property by portal

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

The id of the tenant

Request Body schema: application/json
required
name
required
string [ 3 .. 255 ] characters

The name of the property

type
required
string
Enum: "OCTETSTRING" "INTEGER" "BOOLEAN" "UTF8STRING" "DATE"

Information on a accepted type of property's value

value
required
string non-empty

a value of a property

encryption
string
Default: "NONE"
Enum: "NONE" "SERVER_SIDE_DB"

Info that say is the stored value should be encrypted in DB and what the way

readOnly
boolean
Default: false

A flag that say is the property readOnly

notify
boolean
Default: false

A flag that say is the service notifies changes to the AST Client (e.g. using stream service)

inKeystorage
boolean
Default: false

A flag for special protection mode. I.e. property is associated with so called virtual smartcard on the AST Client.

cpFlags
integer
Default: 0

CACHE_POLICY flags determine, how AST Client processes changes. Allowed values are 0 - NO_CACHING, 512 -SYNCHRONIZE_FROM_SDK, 768 - SYNCHRONIZE_FROM_SSMS

visibility
Array of strings or null
Enum: "CLIENT" "INTERNAL" "EXTERNAL"
userId
required
string [ 3 .. 255 ] characters

An unique Id of a User

astClientId
required
string^([0-9A-HJKMNP-TV-Z]{26})$

An unique Id of a ASTClient in ULID-like format

Responses

Request samples

Content type
application/json
{
  • "name": "CardNumber",
  • "type": "UTF8STRING",
  • "value": "1111-2222-3333-4444",
  • "encryption": "NONE",
  • "readOnly": "false",
  • "notify": "false",
  • "inKeystorage": "false",
  • "cpFlags": "0",
  • "visibility": [
    ],
  • "userId": "123e4567-e89b-12d3-a456-42665544a3f7",
  • "astClientId": "01FH8MDGN9W5C3RXRFNX6G164S"
}

Response samples

Content type
application/json
{
  • "id": "1ZN1FP8NRQ8NHB7Z1CJRZPDBX1"
}

Info for a specific property by propertyId for portal

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

The id of the tenant

propertyId
required
string^([0-9A-HJKMNP-TV-Z]{26})$
Example: 1ZN1FP8NRQ8NHB7Z1CJRZPDBX1

The id of the property to retrieve

Responses

Response samples

Content type
application/json
{
  • "userId": "123e4567-e89b-12d3-a456-42665544a3f7",
  • "astClientId": "01FH8MDGN9W5C3RXRFNX6G164S",
  • "name": "CardNumber",
  • "type": "UTF8STRING",
  • "value": "1111-2222-3333-4444",
  • "encryption": "NONE",
  • "readOnly": "false",
  • "notify": "false",
  • "inKeystorage": "false",
  • "cpFlags": "0",
  • "visibility": [
    ]
}

Delete the property with given propertyId by portal

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

The id of the tenant

propertyId
required
string^([0-9A-HJKMNP-TV-Z]{26})$
Example: 1ZN1FP8NRQ8NHB7Z1CJRZPDBX1

The id of the property to retrieve

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Update the property with given propertyId by portal

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

The id of the tenant

propertyId
required
string^([0-9A-HJKMNP-TV-Z]{26})$
Example: 1ZN1FP8NRQ8NHB7Z1CJRZPDBX1

The id of the property to retrieve

Request Body schema: application/json
required
name
required
string [ 3 .. 255 ] characters

The name of the property

type
required
string
Enum: "OCTETSTRING" "INTEGER" "BOOLEAN" "UTF8STRING" "DATE"

Information on a accepted type of property's value

value
required
string non-empty

a value of a property

encryption
string
Default: "NONE"
Enum: "NONE" "SERVER_SIDE_DB"

Info that say is the stored value should be encrypted in DB and what the way

readOnly
boolean
Default: false

A flag that say is the property readOnly

notify
boolean
Default: false

A flag that say is the service notifies changes to the AST Client (e.g. using stream service)

inKeystorage
boolean
Default: false

A flag for special protection mode. I.e. property is associated with so called virtual smartcard on the AST Client.

cpFlags
integer
Default: 0

CACHE_POLICY flags determine, how AST Client processes changes. Allowed values are 0 - NO_CACHING, 512 -SYNCHRONIZE_FROM_SDK, 768 - SYNCHRONIZE_FROM_SSMS

visibility
Array of strings or null
Enum: "CLIENT" "INTERNAL" "EXTERNAL"
userId
required
string [ 3 .. 255 ] characters

An unique Id of a User

astClientId
required
string^([0-9A-HJKMNP-TV-Z]{26})$

An unique Id of a ASTClient in ULID-like format

Responses

Request samples

Content type
application/json
{
  • "name": "CardNumber",
  • "type": "UTF8STRING",
  • "value": "1111-2222-3333-4444",
  • "encryption": "NONE",
  • "readOnly": "false",
  • "notify": "false",
  • "inKeystorage": "false",
  • "cpFlags": "0",
  • "visibility": [
    ],
  • "userId": "123e4567-e89b-12d3-a456-42665544a3f7",
  • "astClientId": "01FH8MDGN9W5C3RXRFNX6G164S"
}

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Delete a property with given Name by portal

Delete a property by name without AstClientId for the specified userId by authorized portal user.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

The id of the tenant

userId
required
string [ 3 .. 255 ] characters
Example: 1ZN1FP8NRQ8NHB7Z1CJRZPDBX3

The id of the user

propertyName
required
string [ 3 .. 255 ] characters
Example: CardNumber

The name of the AST Client Property

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Delete client's property with given Name by portal

Delete a property by name for the specified userId and astClientId by authorized portal user.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

The id of the tenant

userId
required
string [ 3 .. 255 ] characters
Example: 1ZN1FP8NRQ8NHB7Z1CJRZPDBX3

The id of the user

astClientId
required
string^([0-9A-HJKMNP-TV-Z]{26})$
Example: 1ZN1FP8NRQ8NHB7Z1CJRZPDBX5

The id of the AST Client

propertyName
required
string [ 3 .. 255 ] characters
Example: CardNumber

The name of the AST Client Property

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Localization

List Localizable Templates

Returns a paged list of all available templates.

The template list might be filtered for locales by specifying a standard Accept-Language header. Furthermore, template names can be filtered using the filter query parameter.

path Parameters
tenantId
required
string non-empty

The tenant scope

query Parameters
page
integer <int32> >= 1
Default: 1

The page number (1-based)

page_size
integer <int32> [ 2 .. 100 ]
Default: 20

The number of entries per page, must be between 5 and 100

filter
string^(\*|\*\*|[a-zA-Z]+[\w\-]*(\.[a-zA-Z]+[\w\-]*...
Default: "**"

A template name filter, consisting of a simple glob-like syntax. It may include literal matching, single component wildcards * and multi component wildcards **.

Wildcards are not allowed to directly follow or precede a literal matcher.

Example:

  • template.key matches only template.key (literally)
  • template.* matches template.keyA, template.keyB, template.otherKey, etc.
  • template.*.item matches template.keyA.item, template.keyB.item, template.otherKey.item, etc.
  • template.** matches template.keyA, template.keyB, template.subkey.keyA, template.any.subpath.matches.the.filter, etc.
  • template.**.item matches template.keyA.item, template.keyB.item, template.subkey.keyA.item, template.any.subpath.matches.the.filter.item, etc.
  • template.key* is not allowed
  • template.key** is not allowed
  • *template is not allowed
  • **template is not allowed
  • ** matches everything
  • * matches all template names without a dot
header Parameters
Accept-Language
string^((\*|([a-zA-Z]{1,8}))((?<!\*)-([A-Z0-9]{1,8}...
Default: *
Example: de-DE,en;q=0.7

A header specifying the acceptable locales for the answer.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a New Template

Creates a new template. Requires that a template with the given name doesn't exist yet.

The template definition may already include localized variants for any number of additional locales, but must at least contain a template for the default locale.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string non-empty

The tenant scope

Request Body schema: application/json
required

The template definition

key
required
string (TemplateKey) <= 1024 characters ^[a-zA-Z]+[\w\-]*(\.[a-zA-Z]+[\w\-]*)*$

A template identifier

Must start with a letter, followed by any number of letters, digits, - or _. Optionally, a dot followed by another template identifier might be added.

defaultContent
required
string (TemplateContent) non-empty

The template content

Array of objects

Responses

Request samples

Content type
application/json
{
  • "key": "string",
  • "defaultContent": "string",
  • "locales": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Retrieve Template Content

Retrieves the content of the given template. The desired locale may be passed in terms of standard Accept-Language header. If no such header is sent, the default locale is returned.

path Parameters
tenantId
required
string non-empty

The tenant scope

templateKey
required
string (TemplateKey) <= 1024 characters ^[a-zA-Z]+[\w\-]*(\.[a-zA-Z]+[\w\-]*)*$

The template's key

header Parameters
Accept-Language
string^((\*|([a-zA-Z]{1,8}))((?<!\*)-([A-Z0-9]{1,8}...
Default: *
Example: de-DE,en;q=0.7

A header specifying the acceptable locales for the answer.

Responses

Response samples

Content type
application/json
{
  • "key": "string",
  • "locale": "de-DE",
  • "content": "string"
}

Update Template

Updates an existing template. This offers the option to update the default content, update any existing locale's content, or add new locales.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string non-empty

The tenant scope

templateKey
required
string (TemplateKey) <= 1024 characters ^[a-zA-Z]+[\w\-]*(\.[a-zA-Z]+[\w\-]*)*$

The template's key

Request Body schema: application/json
required

The template patch

defaultContent
string (TemplateContent) non-empty

The template content

Array of objects

Responses

Request samples

Content type
application/json
{
  • "defaultContent": "string",
  • "locales": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Delete Template

Deletes an existing template altogether. All locales and the template itself are removed.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string non-empty

The tenant scope

templateKey
required
string (TemplateKey) <= 1024 characters ^[a-zA-Z]+[\w\-]*(\.[a-zA-Z]+[\w\-]*)*$

The template's key

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Update Template for Locale

Updates the given locale for an existing template. The locale will be added if it didn't exist before.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string non-empty

The tenant scope

templateKey
required
string (TemplateKey) <= 1024 characters ^[a-zA-Z]+[\w\-]*(\.[a-zA-Z]+[\w\-]*)*$

The template's key

locale
required
string (LanguageTag) ^(((en-GB-oed|i-ami|i-bnn|i-default|i-enochia...
Example: de-DE

The template's locale to target

Request Body schema: application/json
required

The template patch

content
required
string (TemplateContent) non-empty

The template content

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Delete Template for Locale

Deletes the given locale for a template. If the locale doesn't exist, this operation does nothing.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string non-empty

The tenant scope

templateKey
required
string (TemplateKey) <= 1024 characters ^[a-zA-Z]+[\w\-]*(\.[a-zA-Z]+[\w\-]*)*$

The template's key

locale
required
string (LanguageTag) ^(((en-GB-oed|i-ami|i-bnn|i-default|i-enochia...
Example: de-DE

The template's locale to target

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Message Sign

Start a TMS

Start a TMS (transaction flow) for a specific user.

Freshness of Authentication

The user can be forced to enter his credentials again in order to be able to view/process the TMS by setting requireFreshnessOfAuthentication to any non-negative value. The semantics are as follows:

  • requiresFreshnessOfAuthentication == -1 - no fresh authentication is required
  • requiresFreshnessOfAuthentication ~= 0..2 - the user always needs to do a fresh authentication
  • requiresFreshnessOfAuthentication > 2 - the user needs to enter his credentials if the last authentication is more than that many seconds older than the retrieval time of the TMS (field retrievedAt in the TMS status)
Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The ID of the tenant to use

Request Body schema: application/json
required

Contains all parameters required to start the transaction

userId
required
string non-empty

The of the user to start a TMS for

required
object (MessageData)

The message data to be displayed to the user

object (AppFilter)

An optional filter to send the TMS only to clients with a specific app

astClientIds
Array of strings (Id) non-empty [ items^[0-7][0-9A-HJKMNP-TV-Z]{25}$ ]

An optional client filter to send the TMS only to specific clients of the user

retrievalTimeout
integer <int32> >= 1
Default: 300

The number of seconds the client is allowed to take for retrieving the TMS message.

tmsTimeout
integer <int32> >= 1
Default: 600

The number of seconds the TMS is allowed to take for completion after retrieval.

requireExplicitAuthentication
boolean
Default: false

Whether the TMS result must be submitted with an specifically authenticated token.

This requires a specific scope in the access token that can be configured in the service configuration.

requireFreshnessOfAuthentication
integer <int32> >= -1
Default: -1

Requires the user to authenticate within a certain time to be able to respond to the TMS. This authentication includes presenting credentials (e.g. the password) to the IDP. If this field is set to x, when responding to the TMS, the token used must be at most x seconds older than the time when the client fetched the TMS.

Setting this to -1 disables the requirement. Any value <= 2 will always trigger a fresh login on the client and will be treated on the server as if the field had been set to 2.

object (PushSpec)

An optional, customizable push notification payload. It allows to specify a custom push notification title and body. Both fields are optional. If they are omitted, TMS will send the following:

Push Notification Title:

  • On a new TMS: com.kobil.ast.tms.newTms.title
  • On a new DM: com.kobil.ast.tms.newDm.title

Push Notification Body:

  • On a new TMS: com.kobil.ast.tms.newTms.body
  • On a new DM: com.kobil.ast.tms.newDm.body

Both fields can also be set to null to indicate that the push message does not have a title or body.

To disable sending push for this TMS or DM, set skip to true (default: false). In that case, title and body will be ignored, if set.

auditMessage
any

An optional message that is written to auditing

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "tmsData": {
    },
  • "appFilter": {
    },
  • "astClientIds": [
    ],
  • "retrievalTimeout": 300,
  • "tmsTimeout": 600,
  • "requireExplicitAuthentication": false,
  • "requireFreshnessOfAuthentication": -1,
  • "push": {
    },
  • "auditMessage": null
}

Response samples

Content type
application/json
{
  • "id": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "status": "STARTED",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "retrievedAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "retrievalTimeout": 0,
  • "tmsTimeout": 0,
  • "userId": "string",
  • "appFilter": {
    },
  • "astClientIds": [
    ]
}

Cancel an Ongoing TMS

Requests to cancel a running TMS. This operation will fail if the TMS is already complete. A TMS is complete if it is in ACCEPTED, REJECTED, TIMEOUT or CANCELLED state.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The ID of the tenant to use

tmsId
required
string (Id) ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

The ID of the TMS

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Get TMS Status

Retrieve the status of a TMS

Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The ID of the tenant to use

tmsId
required
string (Id) ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

The ID of the TMS

Responses

Response samples

Content type
application/json
{
  • "id": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "status": "STARTED",
  • "startedAt": "2019-08-24T14:15:22Z",
  • "retrievedAt": "2019-08-24T14:15:22Z",
  • "completedAt": "2019-08-24T14:15:22Z",
  • "retrievalTimeout": 0,
  • "tmsTimeout": 0,
  • "userId": "string",
  • "appFilter": {
    },
  • "astClientIds": [
    ]
}

Get TMS Result

Retrieve the result of a completed TMS

Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The ID of the tenant to use

tmsId
required
string (Id) ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

The ID of the TMS

Responses

Response samples

Content type
application/json
{
  • "info": {
    },
  • "completedBy": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "signedData": "string",
  • "failureReason": {
    }
}

Decrypt signed TMS Data

Decrypt the signed data and extract the signed content from it. The signed data passed to this endpoint must match the following requirements:

  • It must be byte-by-byte equal to how it was stored encrypted in the database (encrypted_signed_data column)
  • It must match the TMS ID specified in the request URI
  • It must have been encrypted under the same DB master secret as this service is using at the time of request

If any of these requirements are not met, an error will be returned (HTTP Status 400, Error Code 516-51).

This endpoint will also validate the structure and verify the signature of the signed data and check the integrity of the certificate chain. It can only check the validity of the signature and certificate chain at the time of signature creation. No additional effort will be put into checking if the signature or certificate chain is still valid at the time where this endpoint is called.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The ID of the tenant to use

tmsId
required
string (Id) ^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

The ID of the TMS

Request Body schema: application/json
required

Contains the encrypted signed data

required
string or string

The encrypted signed data of a TMS as it was stored in the database, encoded in base64 or base64url

includeCertificates
boolean
Default: false

Whether to include the certificates from the CMS in the response (false by default)

Responses

Request samples

Content type
application/json
{
  • "encryptedSignedData": null,
  • "includeCertificates": false
}

Response samples

Content type
application/json
{
  • "content": "string",
  • "userId": "string",
  • "astClientId": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "signingTime": "2019-08-24T14:15:22Z",
  • "certificates": [
    ]
}

Send a Display Message

Send a display message to a specific user.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string (Tenant) [ 1 .. 255 ] characters
Example: master

The ID of the tenant to use

Request Body schema: application/json
required

Contains all parameters required to start the transaction

userId
required
string non-empty

The of the user to start a TMS for

required
object (MessageData)

The message data to be displayed to the user

object (AppFilter)

An optional filter to send the TMS only to clients with a specific app

astClientIds
Array of strings (Id) non-empty [ items^[0-7][0-9A-HJKMNP-TV-Z]{25}$ ]

An optional client filter to send the TMS only to specific clients of the user

displayMessageTimeout
integer <int32> >= 1
Default: 600

The number of seconds the display message is available for clients to retrieve

object (PushSpec)

An optional, customizable push notification payload. It allows to specify a custom push notification title and body. Both fields are optional. If they are omitted, TMS will send the following:

Push Notification Title:

  • On a new TMS: com.kobil.ast.tms.newTms.title
  • On a new DM: com.kobil.ast.tms.newDm.title

Push Notification Body:

  • On a new TMS: com.kobil.ast.tms.newTms.body
  • On a new DM: com.kobil.ast.tms.newDm.body

Both fields can also be set to null to indicate that the push message does not have a title or body.

To disable sending push for this TMS or DM, set skip to true (default: false). In that case, title and body will be ignored, if set.

auditMessage
any

An optional message that is written to auditing

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "displayMessageData": {
    },
  • "appFilter": {
    },
  • "astClientIds": [
    ],
  • "displayMessageTimeout": 600,
  • "push": {
    },
  • "auditMessage": null
}

Response samples

Content type
application/json
{
  • "id": "01F6MJ6J1AA8HWB7G6XRJB709E"
}

Version

List all platforms

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List all architectures according to given platform name

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

platformName
required
string [ 3 .. 10 ] characters
Example: Android

Name of a App platform to retrieve architectures

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List all versions using pagination

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

query Parameters
page
integer <int32> [ 1 .. 21474837 ]
Default: 1

Number of the requested page, starting at 1

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items per page, maximum is 100.

appName
string [ 1 .. 32 ] characters
Example: appName=Payment application

Name of an App

platform
string >= 3 characters
Example: platform=Android

Platform name of an App

versionLock
boolean

Lock state of a Version

isCheckIntegrity
boolean

isCheckIntegrity flag of a version

versionStr
string
Example: versionStr=1.2.3

String representation of a Version number.

textSearch
string

String parameter to search for a text on app version properties like App Name, Platform, version. TextSearch filter will be applied to the property whose filter is not explicitly set in the request query parameter. For example, if appName query parameter is set to Super App and TextSearch is with Mac, then it will return all app versions whose appName is SuperApp and platform or versionStr contains Mac.

isTextSearch
boolean
Deprecated
Default: false

Deprecated — use textSearch instead.

Enables text search across all string-based search fields. Default is false, meaning all filters are applied with AND logic. When set to true, all string search parameters must have the same non-empty value, which is used as a text query.

The search is performed across fields like app name, platform name, version using OR logic, while non-string filters are still applied with AND logic.

Responses

Response samples

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

Create a version

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

Request Body schema: application/json
required
appName
required
string [ 3 .. 255 ] characters

Name of an App.

platform
required
string [ 1 .. 100 ] characters

Platform name of an App version.

versionStr
required
string^\d+\.\d+\.\d+$

String representation of a version number.

versionLock
boolean

Lock flag of a Version.

isCheckIntegrity
boolean

Check Integrity flag of a Version.

registerUserId
string or null [ 1 .. 255 ] characters

an Id of a user, by which app version can be registered (in case of default 'USER' based registration policy).

policyId
string or null^[0-9A-Za-z]{26}$

ID of a registration policy, backed by ULID format. Either policyId or registerUserId must be provided.

Responses

Request samples

Content type
application/json
{
  • "appName": "string",
  • "platform": "string",
  • "versionStr": "1.2.3",
  • "versionLock": true,
  • "isCheckIntegrity": true,
  • "registerUserId": "string",
  • "policyId": "01F6MJ6J1AA8HWB7G6XRJB709E"
}

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Hierarchical representation of app-version and its properties using pagination

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

query Parameters
page
integer <int32> [ 1 .. 21474837 ]
Default: 1

Number of the requested page, starting at 1

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items per page, maximum is 100.

appName
string [ 1 .. 32 ] characters
Example: appName=Payment application

Name of an App. Also, possible to search for appName which contains given search text, using % character, e.g. Pay% return all versions whose appName start with Pay.

platform
string [ 3 .. 10 ] characters
Example: platform=Android

Platform name of an App. Also, possible to search for platform name which contains given search text, using % character, e.g. AND% return all versions whose platform name start with AND.

versionLock
boolean

Lock state of a Version

isCheckIntegrity
boolean

isCheckIntegrity flag of a version

versionStr
string^%{0,1}\d+\.*\d*\.*\d*%{0,1}$
Example: versionStr=%1.2.3%

String representation of a Version number. Also, possible to search for version which contains given search text, using % character, e.g. 1.0% return all versions which start with 1.0.

Responses

Response samples

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

List distinct version numbers using pagination

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

query Parameters
page
integer <int32> [ 1 .. 21474837 ]
Default: 1

Number of the requested page, starting at 1

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items per page, maximum is 100.

appName
string [ 1 .. 32 ] characters
Example: appName=Payment application

Name of an App. Also, possible to search for appName which contains given search text, using % character, e.g. Pay% return all versions whose appName start with Pay.

platform
string [ 3 .. 10 ] characters
Example: platform=Android

Platform name of an App. Also, possible to search for platform name which contains given search text, using % character, e.g. AND% return all versions whose platform name start with AND.

versionLock
boolean

Lock state of a Version

isCheckIntegrity
boolean

isCheckIntegrity flag of a version

versionStr
string^%{0,1}\d+\.*\d*\.*\d*%{0,1}$
Example: versionStr=%1.2.3%

String representation of a Version number. Also, possible to search for version which contains given search text, using % character, e.g. 1.0% return all versions which start with 1.0.

orderByVersion
string
Enum: "asc" "desc"
Example: orderByVersion=asc

Parameter to specify the result list should be sorted by version number using ascending or descending order.

Responses

Response samples

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

Info for a specific version

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

versionId
required
string^[0-9A-Za-z]{26}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

ID of a Version

Responses

Response samples

Content type
application/json
{
  • "architectureIntegrities": [
    ],
  • "id": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "tenantId": "vertx",
  • "version": "1108101562371",
  • "sdkVersion": "1.2.333",
  • "appName": "string",
  • "platform": "string",
  • "versionStr": "1.2.3",
  • "versionLock": true,
  • "isCheckIntegrity": true,
  • "registerUserId": "string",
  • "policyId": "01F6MJ6J1AA8HWB7G6XRJB709E"
}

Update a version

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

versionId
required
string^[0-9A-Za-z]{26}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

ID of a Version

Request Body schema: application/json
required
appName
required
string [ 3 .. 255 ] characters

Name of an App.

platform
required
string [ 1 .. 100 ] characters

Platform name of an App version.

versionStr
required
string^\d+\.\d+\.\d+$

String representation of a version number.

versionLock
boolean

Lock flag of a Version.

isCheckIntegrity
boolean

Check Integrity flag of a Version.

registerUserId
string or null [ 1 .. 255 ] characters

an Id of a user, by which app version can be registered (in case of default 'USER' based registration policy).

policyId
string or null^[0-9A-Za-z]{26}$

ID of a registration policy, backed by ULID format. Either policyId or registerUserId must be provided.

Responses

Request samples

Content type
application/json
{
  • "appName": "string",
  • "platform": "string",
  • "versionStr": "1.2.3",
  • "versionLock": true,
  • "isCheckIntegrity": true,
  • "registerUserId": "string",
  • "policyId": "01F6MJ6J1AA8HWB7G6XRJB709E"
}

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

delete specific version

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

versionId
required
string^[0-9A-Za-z]{26}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

ID of a Version

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

lock/unlock specific version

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

versionId
required
string^[0-9A-Za-z]{26}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

ID of a Version

Request Body schema: application/json
required
versionLock
required
boolean

Locked flag of a Version.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "tenantId": "vertx",
  • "version": "1108101562371",
  • "sdkVersion": "1.2.333",
  • "appName": "string",
  • "platform": "string",
  • "versionStr": "1.2.3",
  • "versionLock": true,
  • "isCheckIntegrity": true,
  • "registerUserId": "string",
  • "policyId": "01F6MJ6J1AA8HWB7G6XRJB709E"
}

Delete App Registration

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

versionId
required
string^[0-9A-Za-z]{26}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

ID of a Version

query Parameters
architectureName
required
string [ 3 .. 10 ] characters
Example: architectureName=x86

Architecture Name of an App Version

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Get list of registered architectures

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

versionId
required
string^[0-9A-Za-z]{26}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

ID of a Version

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a list of Apps

Get a list of Apps

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

query Parameters
page
integer <int32> [ 1 .. 21474837 ]
Default: 1

Number of the requested page, starting at 1

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items per page, maximum is 100.

appName
string [ 1 .. 32 ] characters
Example: appName=Payment application

Name of an App

Responses

Response samples

Content type
application/json
{
  • "tenantId": "ks-management",
  • "appName": "Maverick Payment",
  • "pushNotificationConfig": {
    }
}

Save App configuration with app-name and optionally push notification config

Save App configuration with app-name and optionally push notification config

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

appName
required
string [ 1 .. 32 ] characters
Example: Payment application

Name of an App

Request Body schema: application/json
required
categories
required
Array of strings (PushCategories) non-empty unique
Items Enum: "chat" "payment" "tms"
androidApiKey
string or null <= 255 characters

Legacy Firebase Cloud Messaging (FCM) server API key used for sending Android push notifications.

Legacy FCM server API is not supported, use fcmServiceAccountJSON for FCM HTTP v1 API authentication.

fcmServiceAccountJSON
string or null <= 15360 characters

Base64-encoded Firebase service account JSON credentials used for Firebase Cloud Messaging (FCM) HTTP v1 API authentication.

The original content must be the complete JSON service account file downloaded from Firebase or Google Cloud Console.

Required for FCM integration.

iosApnsCertificate
string or null <= 46080 characters

Base64-encoded APNs certificate for push notifications.

Required for APNs certificate-based authentication.

Supported certificate formats before Base64 encoding:

  • DER certificate
  • PEM certificate

The value may optionally include the Data URL prefix: data:application/x-x509-ca-cert;base64,

Examples:

  • Base64-encoded DER certificate
  • Base64-encoded PEM certificate
  • Data URL prefix with a Base64-encoded certificate
iosApnsPrivateKey
string or null <= 10240 characters

Base64-encoded APNS private key for push notifications.

Required for both certificate-based and token-based APNs authentication.

Supported private key formats before Base64 encoding:

  • PKCS#8 PEM private key
  • PKCS#8 DER private key
  • PKCS#1 PEM private key
  • PKCS#1 DER private key

The value may optionally include the Data URL prefix: data:application/x-pem-file;base64,

Examples:

  • Base64-encoded DER private key
  • Base64-encoded PEM private key
  • Data URL prefix with a Base64-encoded private key
iosApnsTeamId
string or null <= 32 characters

Apple Developer Team ID associated with the APNs authentication key.

Required for token-based APNs authentication.

iosApnsKeyId
string or null <= 32 characters

Apple Key ID associated with the APNs authentication key. Required for token-based APNs authentication.

iosBundleId
string or null <= 128 characters

iOS application bundle identifier used as the APNs topic.

Required for both certificate-based and token-based APNs authentication.

iosIsDevelopment
boolean or null

Determines whether the APNs sandbox or production environment is used.

Required when any APNs configuration field is provided.

hpkClientId
string or null <= 64 characters

Huawei Push Kit (HPK) client identifier.

Must be provided together with hpkClientSecret.

hpkClientSecret
string or null <= 256 characters

Huawei Push Kit (HPK) client secret used for authentication.

Must be provided together with hpkClientId.

Responses

Request samples

Content type
application/json
{
  • "categories": [
    ],
  • "androidApiKey": "U0dWc2JHOGdkMjl5YkdRaA==",
  • "fcmServiceAccountJSON": "eyAiY2xpZW50X2lkIjogImNsaWVudC1pZCIsICJjbGllbnRfc2VjcmV0IjogInNlY3JldCJ9",
  • "iosApnsCertificate": "data:application/x-x509-ca-cert;base64,Q0VSVElGSUNBVEU=",
  • "iosApnsPrivateKey": "data:application/x-pem-file;base64,UFJJVkFURUtFWQ==",
  • "iosApnsTeamId": "TEAM123456",
  • "iosApnsKeyId": "KEY1234567",
  • "iosBundleId": "com.example.myapp",
  • "iosIsDevelopment": true,
  • "hpkClientId": "huawei-client-id",
  • "hpkClientSecret": "huawei-client-secret"
}

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Update App configuration

Update App configuration

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

appName
required
string [ 1 .. 32 ] characters
Example: Payment application

Name of an App

Request Body schema: application/json
required
categories
required
Array of strings (PushCategories) non-empty unique
Items Enum: "chat" "payment" "tms"
androidApiKey
string or null <= 255 characters

Legacy Firebase Cloud Messaging (FCM) server API key used for sending Android push notifications.

Legacy FCM server API is not supported, use fcmServiceAccountJSON for FCM HTTP v1 API authentication.

fcmServiceAccountJSON
string or null <= 15360 characters

Base64-encoded Firebase service account JSON credentials used for Firebase Cloud Messaging (FCM) HTTP v1 API authentication.

The original content must be the complete JSON service account file downloaded from Firebase or Google Cloud Console.

Required for FCM integration.

iosApnsCertificate
string or null <= 46080 characters

Base64-encoded APNs certificate for push notifications.

Required for APNs certificate-based authentication.

Supported certificate formats before Base64 encoding:

  • DER certificate
  • PEM certificate

The value may optionally include the Data URL prefix: data:application/x-x509-ca-cert;base64,

Examples:

  • Base64-encoded DER certificate
  • Base64-encoded PEM certificate
  • Data URL prefix with a Base64-encoded certificate
iosApnsPrivateKey
string or null <= 10240 characters

Base64-encoded APNS private key for push notifications.

Required for both certificate-based and token-based APNs authentication.

Supported private key formats before Base64 encoding:

  • PKCS#8 PEM private key
  • PKCS#8 DER private key
  • PKCS#1 PEM private key
  • PKCS#1 DER private key

The value may optionally include the Data URL prefix: data:application/x-pem-file;base64,

Examples:

  • Base64-encoded DER private key
  • Base64-encoded PEM private key
  • Data URL prefix with a Base64-encoded private key
iosApnsTeamId
string or null <= 32 characters

Apple Developer Team ID associated with the APNs authentication key.

Required for token-based APNs authentication.

iosApnsKeyId
string or null <= 32 characters

Apple Key ID associated with the APNs authentication key. Required for token-based APNs authentication.

iosBundleId
string or null <= 128 characters

iOS application bundle identifier used as the APNs topic.

Required for both certificate-based and token-based APNs authentication.

iosIsDevelopment
boolean or null

Determines whether the APNs sandbox or production environment is used.

Required when any APNs configuration field is provided.

hpkClientId
string or null <= 64 characters

Huawei Push Kit (HPK) client identifier.

Must be provided together with hpkClientSecret.

hpkClientSecret
string or null <= 256 characters

Huawei Push Kit (HPK) client secret used for authentication.

Must be provided together with hpkClientId.

Responses

Request samples

Content type
application/json
{
  • "categories": [
    ],
  • "androidApiKey": "U0dWc2JHOGdkMjl5YkdRaA==",
  • "fcmServiceAccountJSON": "eyAiY2xpZW50X2lkIjogImNsaWVudC1pZCIsICJjbGllbnRfc2VjcmV0IjogInNlY3JldCJ9",
  • "iosApnsCertificate": "data:application/x-x509-ca-cert;base64,Q0VSVElGSUNBVEU=",
  • "iosApnsPrivateKey": "data:application/x-pem-file;base64,UFJJVkFURUtFWQ==",
  • "iosApnsTeamId": "TEAM123456",
  • "iosApnsKeyId": "KEY1234567",
  • "iosBundleId": "com.example.myapp",
  • "iosIsDevelopment": true,
  • "hpkClientId": "huawei-client-id",
  • "hpkClientSecret": "huawei-client-secret"
}

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Get App for given app-name

Get App for given app-name

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

appName
required
string [ 1 .. 32 ] characters
Example: Payment application

Name of an App

Responses

Response samples

Content type
application/json
{
  • "tenantId": "ks-management",
  • "appName": "Maverick Payment",
  • "pushNotificationConfig": {
    }
}

Delete App for given app-name, also delete related versions

Delete App for given app-name, also delete related versions

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

appName
required
string [ 1 .. 32 ] characters
Example: Payment application

Name of an App

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

List Apps with it's latest version information using pagination

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

query Parameters
page
integer <int32> [ 1 .. 21474837 ]
Default: 1

Number of the requested page, starting at 1

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items per page, maximum is 100.

appName
string [ 1 .. 32 ] characters
Example: appName=Payment application

Name of an App

platform
string >= 3 characters
Example: platform=Android

Platform name of an App

category
Array of strings <= 3 items
Example: category=chat

Array of App Push Notifications Categories

credential
Array of strings <= 3 items
Example: credential=apns

Array of App Push Notifications Credentials

textSearch
string

String parameter to search for a text on app version properties like App Name, Platform, version, app categories, app credential types. TextSearch filter will be applied to the property whose filter is not explicitly set in the request query parameter. For example, if appName query parameter is set to Super App and TextSearch is with Mac, then it will return all app versions whose appName is SuperApp and (platform or versionStr or app categories or app credential types) contains Mac.

isTextSearch
boolean
Deprecated
Default: false

Deprecated — use textSearch instead.

Enables text search across all string-based search fields. Default is false, meaning all filters are applied with AND logic. When set to true, all string search parameters must have the same non-empty value, which is used as a text query.

The search is performed across fields like app name, platform name, categories, app credential using OR logic, while non-string filters are still applied with AND logic.

Responses

Response samples

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

Gets a list of registration policies by tenant

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a new registration policy for an app version.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

Request Body schema: application/json
required
name
required
string [ 1 .. 50 ] characters

Name of a registration policy.

type
required
string
Value: "QUORUM"

Type of a registration policy.

required
object

additional parameters object

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Gets a specific registration policy details

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

policyId
required
string^[0-9A-Za-z]{26}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

ID of a Policy

Responses

Response samples

Content type
application/json
{
  • "id": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "name": "string",
  • "type": "QUORUM",
  • "parameters": {
    }
}

Deletes a registration policy

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

policyId
required
string^[0-9A-Za-z]{26}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

ID of a Policy

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Get a vote for a version and an architecture name.

Returns voting information with a list of clients who voted with their integrityCheckIds using pagination. ArchitectureName is a required parameter and can be null or omitted only for versions of non-architecture platforms(such as Linux).

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

versionId
required
string^[0-9A-Za-z]{26}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

ID of a Version

query Parameters
architectureName
required
string [ 3 .. 10 ] characters
Example: architectureName=x86

Architecture Name of an App Version

integrityCheckId
string or null = 22 characters

Id of integrityCheckValue

page
integer <int32> [ 1 .. 21474837 ]
Default: 1

Number of the requested page, starting at 1

pageSize
integer <int32> [ 1 .. 100 ]
Default: 20

Number of items per page, maximum is 100.

Responses

Response samples

Content type
application/json
{
  • "versionId": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "appName": "string",
  • "platform": "iOS",
  • "versionStr": "1.2.3",
  • "architecture": "x86",
  • "votes": [
    ],
  • "metadata": {
    }
}

Reset the voting process for an app version, either for a specific architecture or for all architectures.

Resets the ongoing voting process for an app version, either for a single architecture or for all architectures. If voting has not yet succeeded for an architecture, it starts over again. If voting has succeeded for an architecture, registration state is retained and only votes are deleted.

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

versionId
required
string^[0-9A-Za-z]{26}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

ID of a Version

query Parameters
architectureName
string [ 3 .. 10 ] characters
Example: architectureName=x86

Architecture Name of an App Version

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}

Get a vote summary for a version and an architecture name.

Returns voting summary information, including the number of clients that voted, grouped by integrityCheckId. architectureName is a required parameter, but can be omitted or set to null for versions targeting non-architecture platforms (such as Linux).

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: ks-management

ID of a Tenant

versionId
required
string^[0-9A-Za-z]{26}$
Example: 01F6MJ6J1AA8HWB7G6XRJB709E

ID of a Version

query Parameters
architectureName
required
string [ 3 .. 10 ] characters
Example: architectureName=x86

Architecture Name of an App Version

Responses

Response samples

Content type
application/json
{
  • "versionId": "01F6MJ6J1AA8HWB7G6XRJB709E",
  • "appName": "string",
  • "platform": "iOS",
  • "versionStr": "1.2.3",
  • "architecture": "x86",
  • "policy": {
    },
  • "votes": [
    ]
}

Webhooks

Create a Nonce

Create a Nonce for user

Information about the optional expectedUserId property in request body payload:

  • Optional request body payload property expectedUserId used for enable additional checking in run callback endpoint process
  • In case when expectedUserId not null and userId not match to expectedUserId, callback endpoint PUT /v1/tenants/{tenantId}/clients/events returns response with code 403 and suitable error

Information about the callback:

method: HTTP POST

type: application/json

Callback data:

  • timestampMillis: Creation timestamp in milliseconds, type: number, format: int64
  • nonce: Nonce ID, type: string
  • portalSessionId: Tracking Id, type: string, maxLength: 255
  • loginEvent: The login event data in callback, type: object
  • astClientId: AST Client id in ULID format, type: string
  • userId: User id, type: string, minLength: 1, maxLength: 255

Example:

{
  "timestampMillis": 1712053389839,
  "nonce": "01HTF57W1JXYPD3WE75XR7TZGQ",
  "portalSessionId": "94a58058-8a7a-4339-8ca1-6a586b2b66e1",
  "loginEvent": {
    "astClientId": "01HTF58BGBPVDZCNTXS6ZBYE5H",
    "userId: "be58b4d6-da29-4bf5-81d0-8c6d551f295d"
  }
}
Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: vertx

The id of the tenant

query Parameters
type
string
Default: "default"
Enum: "default" "short"

A nonce type

Request Body schema: application/json
required
action
required
string
Enum: "LOGIN_NONCE" "TMS_NONCE"

The action for which nonce is going to be created

required
object

The payload containing all needed information for nonce creation

Responses

Request samples

Content type
application/json
{
  • "action": "LOGIN_NONCE",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "nonce": "1ZN1FP8NRQ8NHB7Z1CJRZPDBX1",
  • "type": "LOGIN_NONCE",
  • "expiresAt": 2650615161452
}

Create a webhook

Create a new webhook

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: vertx

The id of the tenant

Request Body schema: application/json
required
filter
required
string (The webhook filter) [ 3 .. 4000 ] characters

The filter is a string of the form <field><ws?><operator><ws?><value><ws?><flags?> where <ws?> denotes optional whitespace.

<field> one of the field of the webhook event (See Async API documentation for details) specified below:

  • type
  • event

<operator> can be one of the following operators known from CSS attribute selectors:

  • = - is equal to
  • != - is not equal to
  • <> - is not equal to
  • ^= - starts with
  • $= - ends with
  • *= - contains
  • > - greater than
  • >= - greater than or equal to
  • < - less than
  • <= - less than or equal to
  • like - sql like(_ - any one character, % - zero, one or multiple characters)
  • in - equal to any value in a list
  • !in - not equal to all values in a list

<value> is a string consisting of a-z, A-Z, 0-9, - and _ or '<any character except to \'>', `<any character except to \`>`, "<any character except to \">"

<flags> is an optionally joined list of characters enclosed in square braces and may contain the following flags:

  • [i] | [I] - perform all matching case-insensitive

The filter by several fields or values can be specified using logical operators and brackets.

The logical operator can be one of several aliases for or and and operators:

  • or | OR | || - logical or operator
  • and | AND | && - logical and operator

Brackets:

  • ( - left bracket
  • ) - right bracket

Examples:

  • type=domain matches all webhook events with type of "domain" (case-sensitive)
  • type=domain[i] matches all webhook events with type of "domain" (case-insensitive)
  • type=domain or type=technical matches all webhook events with type of "domain" or "technical". Another form of this filter is type in {domain, technical}
  • type=domain AND event=TMS_RESULT_AVAILABLE matches all webhook events with type of "domain" and event of "TMS_RESULT_AVAILABLE"
  • (type=domain or type=technical) and event=TMS_RESULT_AVAILABLE matches all webhook events with type of "domain" or "technical" and event of "TMS_RESULT_AVAILABLE"
callbackUrl
required
string <uri> <= 4000 characters

The callback URL

authType
string
Default: "NONE"
Enum: "NONE" "BASIC"

The authentication type

BasicAuthCredentials (object)

Authentication credentials. Required if the authentication type is not NONE.

active
boolean
Default: true

Is a webhook active

Responses

Request samples

Content type
application/json
{
  • "filter": "type=domain and event=TMS_RESULT_AVAILABLE",
  • "callbackUrl": "http://test_callback_url.my",
  • "authType": "NONE",
  • "authCredentials": {
    },
  • "active": "true"
}

Response samples

Content type
application/json
{
  • "id": "01FH8MDGN9W5C3RXRFNX6G164S",
  • "tenantId": "ks-management",
  • "filter": "type=domain and event=TMS_RESULT_AVAILABLE",
  • "callbackUrl": "http://test_callback_url.my",
  • "authType": "BASIC",
  • "authCredentials": {
    },
  • "active": "true",
  • "createdAt": "2023-09-20T13:21:48Z",
  • "createdBy": "bob",
  • "modifiedAt": "2023-09-20T15:21:48Z",
  • "modifiedBy": "carol"
}

Find webhooks

Find webhooks

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: vertx

The id of the tenant

query Parameters
page
integer <int32> >= 1
Default: 1

The page number (1-based)

page_size
integer <int32> [ 5 .. 100 ]
Default: 20

The number of entries per page, must be between 5 and 100

filter
Array of strings[ items[a-zA-Z]+\s*(=|\!=|\^=|\$=|\*=)\s*(""|[a-zA-Z... ]

Filter for specific webhooks.

This parameter is repeatable and multiple filters will be applied using logical AND.

A filter is a string of the form <field><ws?><operator><ws?><value><ws?><flags?> where <ws?> denotes optional whitespace.

<field> one of the field of Webhook specified below:

  • id
  • active

<operator> can be one of the following operators known from CSS attribute selectors:

  • = - is equal to
  • != - is not equal to
  • <> - is not equal to
  • ^= - starts with
  • $= - ends with
  • *= - contains
  • > - greater than
  • >= - greater than or equal to
  • < - less than
  • <= - less than or equal to
  • like - sql like(_ - any one character, % - zero, one or multiple characters)
  • in - equal to any value in a list
  • !in - not equal to all values in a list

<value> is a string consisting of a-z, A-Z, 0-9, - and _ or '<any character except to \'>', `<any character except to \`>`, "<any character except to \">"

  • null | NULL without any quotes could be used only with = and != operators. It used to check entity for null value

` is an optionally joined list of characters enclosed in square braces and may contain the following flags:

  • [i] | [I] - perform all matching case-insensitive

<logicalOperator> can be one of several aliases for or and and operators:

  • or | OR | || - logical or operator
  • and | AND | && - logical and operator

<bracket> - can be one of:

  • ( - left bracket
  • ) - right bracket

Examples:

  • id = 01JJ17S93YV1WF1WGF6SMEES7Z find a webhook with id equal to 01JJ17S93YV1WF1WGF6SMEES7Z
  • id in { 01JJ17S93YV1WF1WGF6SMEES7Z, 01JJ17SCF5AEDJFH2FBDMB6TVN} find all webhooks with id equal to 01JJ17S93YV1WF1WGF6SMEES7Z or 01JJ17SCF5AEDJFH2FBDMB6TVN
  • active = true find all active webhooks

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a webhook

Get a webhook

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: vertx

The id of the tenant

webhookId
required
string^([0-9A-HJKMNP-TV-Z]{26})$
Example: 01FH8MDGN9W5C3RXRFNX6G164S

An unique ID of a webhook in ULID-like format

Responses

Response samples

Content type
application/json
{
  • "id": "01FH8MDGN9W5C3RXRFNX6G164S",
  • "tenantId": "ks-management",
  • "filter": "type=domain and event=TMS_RESULT_AVAILABLE",
  • "callbackUrl": "http://test_callback_url.my",
  • "authType": "BASIC",
  • "authCredentials": {
    },
  • "active": "true",
  • "createdAt": "2023-09-20T13:21:48Z",
  • "createdBy": "bob",
  • "modifiedAt": "2023-09-20T15:21:48Z",
  • "modifiedBy": "carol"
}

Update a webhook

Update a webhook

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: vertx

The id of the tenant

webhookId
required
string^([0-9A-HJKMNP-TV-Z]{26})$
Example: 01FH8MDGN9W5C3RXRFNX6G164S

An unique ID of a webhook in ULID-like format

Request Body schema: application/json
required
filter
required
string (The webhook filter) [ 3 .. 4000 ] characters

The filter is a string of the form <field><ws?><operator><ws?><value><ws?><flags?> where <ws?> denotes optional whitespace.

<field> one of the field of the webhook event (See Async API documentation for details) specified below:

  • type
  • event

<operator> can be one of the following operators known from CSS attribute selectors:

  • = - is equal to
  • != - is not equal to
  • <> - is not equal to
  • ^= - starts with
  • $= - ends with
  • *= - contains
  • > - greater than
  • >= - greater than or equal to
  • < - less than
  • <= - less than or equal to
  • like - sql like(_ - any one character, % - zero, one or multiple characters)
  • in - equal to any value in a list
  • !in - not equal to all values in a list

<value> is a string consisting of a-z, A-Z, 0-9, - and _ or '<any character except to \'>', `<any character except to \`>`, "<any character except to \">"

<flags> is an optionally joined list of characters enclosed in square braces and may contain the following flags:

  • [i] | [I] - perform all matching case-insensitive

The filter by several fields or values can be specified using logical operators and brackets.

The logical operator can be one of several aliases for or and and operators:

  • or | OR | || - logical or operator
  • and | AND | && - logical and operator

Brackets:

  • ( - left bracket
  • ) - right bracket

Examples:

  • type=domain matches all webhook events with type of "domain" (case-sensitive)
  • type=domain[i] matches all webhook events with type of "domain" (case-insensitive)
  • type=domain or type=technical matches all webhook events with type of "domain" or "technical". Another form of this filter is type in {domain, technical}
  • type=domain AND event=TMS_RESULT_AVAILABLE matches all webhook events with type of "domain" and event of "TMS_RESULT_AVAILABLE"
  • (type=domain or type=technical) and event=TMS_RESULT_AVAILABLE matches all webhook events with type of "domain" or "technical" and event of "TMS_RESULT_AVAILABLE"
callbackUrl
required
string <uri> <= 4000 characters

The callback URL

authType
string
Default: "NONE"
Enum: "NONE" "BASIC"

The authentication type

BasicAuthCredentials (object)

Authentication credentials. Required if the authentication type is not NONE.

active
boolean
Default: true

Is a webhook active

Responses

Request samples

Content type
application/json
{
  • "filter": "type=domain and event=TMS_RESULT_AVAILABLE",
  • "callbackUrl": "http://test_callback_url.my",
  • "authType": "NONE",
  • "authCredentials": {
    },
  • "active": "true"
}

Response samples

Content type
application/json
{
  • "id": "01FH8MDGN9W5C3RXRFNX6G164S",
  • "tenantId": "ks-management",
  • "filter": "type=domain and event=TMS_RESULT_AVAILABLE",
  • "callbackUrl": "http://test_callback_url.my",
  • "authType": "BASIC",
  • "authCredentials": {
    },
  • "active": "true",
  • "createdAt": "2023-09-20T13:21:48Z",
  • "createdBy": "bob",
  • "modifiedAt": "2023-09-20T15:21:48Z",
  • "modifiedBy": "carol"
}

Delete a webhook

Delete a webhook

Authorizations:
BearerAuth
path Parameters
tenantId
required
string [ 3 .. 255 ] characters
Example: vertx

The id of the tenant

webhookId
required
string^([0-9A-HJKMNP-TV-Z]{26})$
Example: 01FH8MDGN9W5C3RXRFNX6G164S

An unique ID of a webhook in ULID-like format

Responses

Response samples

Content type
application/json
{
  • "message": "Some error message",
  • "code": "402",
  • "subsystem": 519
}