OMNIKEY Cloud API — Virtual Configuration Card Service v1 (1.0)

Download OpenAPI specification:

Authentication

Authenticates a user with the username and password provided in the JSON request.

Authenticates a user with username and password credentials supplied in a JSON request body. No existing bearer token is required.

Send Content-Type: application/json with both username and password set to nonblank values. On success, HTTP 200 returns the JWT access token in token and the firstName and lastName profile fields. Include the returned JWT as a Bearer token in the Authorization header of subsequent API requests.

For this username/password flow, HTTP 400 indicates malformed JSON, missing or blank credentials, or no applicable authentication request. HTTP 401 indicates rejected credentials. HTTP 500 indicates an unexpected authentication error.

header Parameters
api-version
string
Default: 2.0

Uses API version 2.0. Version 2.0 is the default when no API version is specified.

Request Body schema: application/json

JSON object containing the username and password credentials. Both values must be nonblank.

username
required
string

Username for authentication, typically an email address or unique identifier.

password
required
string >= 8 characters

Password associated with the username for authentication.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "firstName": "",
  • "lastName": "",
  • "token": ""
}

Key Management

Retrieves available keysets based on the provided filter.

Discover key references before creating VCC requests. Requires a bearer token with the HidOrigo role. The optional filter is validated as an ICE or MOB prefix. The response is a list of accessible key references, not an access token. This synchronous operation has no request-ownership or Retry-After behavior.

Authorizations:
Bearer
query Parameters
filter
string

Optional filter to narrow down keysets (MOB or ICE)

header Parameters
api-version
string

Optional API version header. Set api-version to 1.0 to select version 1.0. If this header is omitted, the service assumes the default API version, 1.0.

Responses

Response samples

Content type
[
  • "ICE2811"
]

Creates a VCC generation request for a device.

Starts asynchronous VCC generation. Requires a bearer token with the HidOrigo role, valid Secure Element parameters (UserName and EngineID) and a cardType, plus card-type-specific preferences. P000, P001, and MKYD require a keyset. P002 and P003 require an empty keyset. P000 and P001 reject MOB keysets. HTTP 202 contains the requestGuid and means accepted, not completed.

Wait 5 seconds before the first status check and between subsequent pending status checks for every cardType. Measure each wait from receipt of the preceding response and honor any longer server-provided Retry-After. Poll request status, not the result endpoint, and retrieve the result only after RanToCompletion, without an additional polling delay. Stop polling on Faulted or Canceled and handle the terminal outcome.

Keep at most 20 concurrently active end-to-end VCC flows per customer integration. An active flow starts when a request is accepted and ends with successful result retrieval or terminal failure; it is not a named user, HTTP request-per-second budget, or enforced server limit. Latency can rise at this concurrency. Wait client-side before starting additional work, and lower concurrency when latency rises.

Authorizations:
Bearer
header Parameters
api-version
string

Optional API version header. Set api-version to 1.0 to select version 1.0. If this header is omitted, the service assumes the default API version, 1.0.

Request Body schema:

The Virtual Configuration Card generation request payload

userName
required
string

Username associated with the VCC request.

cardType
required
string
Enum: "P000" "P001" "P002" "P003" "MKYD"

Type of card for which the VCC is being generated.

keyset
required
string <= 8 characters

Keyset used for VCC generation.

ecpTci
string or null[0-9a-fA-F]{8}

Optional. Overrides the Seos Terminal Capabilities Identifier (TCI) in the Enhanced Contactless Polling (ECP) frame. Provide your own 8-character hex TCI when required — for example for Transact.

First byte represents Terminal Sub-Type, other bytes represent Terminal Data.

object (Preferences)
engineID
required
string

EngineID of Secure Element

owner
required
string

Id representing the creator of the request

Responses

Request samples

Content type
{
  • "userName": "2B0000000000",
  • "cardType": "P000",
  • "keyset": "ICE2811",
  • "ecpTci": "00000000",
  • "preferences": {
    },
  • "engineID": "string",
  • "owner": "string"
}

Response samples

Content type
{
  • "requestGuid": "08572d5c-bc3d-4b7d-8874-ffb374695c4d",
  • "status": "Created",
  • "creationDateTime": "2019-08-24T14:15:22Z"
}

Returns SNMP configuration with requested configuration keys. Load SNMP messages in the exact order returned; do not reorder them.

Returns the SNMP configuration for a completed Virtual Configuration Card request. Load the SNMP messages onto the device in the exact order returned; do not reorder them.

Retrieves VCC output for an owned request. Requires a bearer token with the HidOrigo role and a GUID request identifier. Pending work returns HTTP 202 with Retry-After: 5. Retrieve the result only after successful completion.

Wait 5 seconds before the first status check and between subsequent pending status checks for every cardType. Measure each wait from receipt of the preceding response and honor any longer server-provided Retry-After. Poll request status, not the result endpoint, and retrieve the result only after RanToCompletion, without an additional polling delay. Stop polling on Faulted or Canceled and handle the terminal outcome.

Keep at most 20 concurrently active end-to-end VCC flows per customer integration. An active flow starts when a request is accepted and ends with successful result retrieval or terminal failure; it is not a named user, HTTP request-per-second budget, or enforced server limit. Latency can rise at this concurrency. Wait client-side before starting additional work, and lower concurrency when latency rises.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

The unique identifier of the configuration request

header Parameters
api-version
string

Optional API version header. Set api-version to 1.0 to select version 1.0. If this header is omitted, the service assumes the default API version, 1.0.

Responses

Response samples

Content type
{
  • "engineID": "2B00000000000000000000000",
  • "userName": "2B0000000000",
  • "snmpMessages": [
    ],
  • "cardType": "P000"
}

Status

Returns the status of a previously submitted request.

Reads the status of an owned request. Requires a bearer token with the HidOrigo role and a GUID request identifier. This endpoint always returns HTTP 200 with the current status, including nonterminal states, and Retry-After: 5.

Wait 5 seconds before the first status check and between subsequent pending status checks for every cardType. Measure each wait from receipt of the preceding response and honor any longer server-provided Retry-After. Poll request status, not the result endpoint, and retrieve the result only after RanToCompletion, without an additional polling delay. Stop polling on Faulted or Canceled and handle the terminal outcome.

Keep at most 20 concurrently active end-to-end VCC flows per customer integration. An active flow starts when a request is accepted and ends with successful result retrieval or terminal failure; it is not a named user, HTTP request-per-second budget, or enforced server limit. Latency can rise at this concurrency. Wait client-side before starting additional work, and lower concurrency when latency rises.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

The unique identifier of the request

header Parameters
api-version
string

Optional API version header. Set api-version to 1.0 to select version 1.0. If this header is omitted, the service assumes the default API version, 1.0.

Responses

Response samples

Content type
{
  • "requestGuid": "08572d5c-bc3d-4b7d-8874-ffb374695c4d",
  • "status": "Created",
  • "creationRequestType": "Vcc",
  • "problemDetails": "Error description"
}
Docs1.0.6