Token

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/x-road-global/json-schema/x-road-global-token-schema.json",
  "title": "Token",
  "description": "Token. Also includes the possible actions that can be done to this object, e.g DELETE (only for token related operations and does not consider user authorization).",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/x-road-global-security-server-admin-openapi.yml#/components/schemas/Token",
  "type": "object",
  "required": [
    "id",
    "name",
    "type",
    "keys",
    "status",
    "logged_in",
    "available",
    "saved_to_configuration",
    "read_only"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "text",
      "description": "token id",
      "minLength": 1,
      "readOnly": true
    },
    "name": {
      "type": "string",
      "format": "text",
      "description": "token name",
      "minLength": 1,
      "maxLength": 255
    },
    "type": {
      "$ref": "#/$defs/TokenType"
    },
    "keys": {
      "type": "array",
      "description": "token keys",
      "uniqueItems": true,
      "items": {
        "$ref": "#/$defs/Key"
      }
    },
    "status": {
      "$ref": "#/$defs/TokenStatus"
    },
    "logged_in": {
      "type": "boolean",
      "description": "if the token has been logged in to"
    },
    "available": {
      "type": "boolean",
      "description": "if the token is available"
    },
    "saved_to_configuration": {
      "type": "boolean",
      "description": "if the token is saved to configuration"
    },
    "read_only": {
      "type": "boolean",
      "description": "if the token is read-only"
    },
    "serial_number": {
      "type": "string",
      "format": "text",
      "description": "serial number of the token"
    },
    "token_infos": {
      "type": "array",
      "description": "Contains label-value pairs of information",
      "items": {
        "$ref": "#/$defs/KeyValuePair"
      }
    },
    "possible_actions": {
      "$ref": "#/$defs/PossibleActions"
    }
  },
  "$defs": {
    "CertificateDetails": {
      "type": "object",
      "description": "certificate details for any kind of certificate (TLS, auth, sign)",
      "required": [
        "issuer_distinguished_name",
        "issuer_common_name",
        "subject_distinguished_name",
        "subject_common_name",
        "not_before",
        "not_after",
        "serial",
        "version",
        "signature_algorithm",
        "signature",
        "public_key_algorithm",
        "rsa_public_key_modulus",
        "rsa_public_key_exponent",
        "hash",
        "key_usages",
        "subject_alternative_names"
      ],
      "properties": {
        "issuer_distinguished_name": {
          "type": "string",
          "format": "text",
          "description": "certificate issuer distinguished name",
          "minLength": 1,
          "maxLength": 255
        },
        "issuer_common_name": {
          "type": "string",
          "format": "text",
          "description": "certificate issuer common name",
          "minLength": 1,
          "maxLength": 255
        },
        "subject_distinguished_name": {
          "type": "string",
          "format": "text",
          "description": "certificate subject distinguished name",
          "minLength": 1,
          "maxLength": 255
        },
        "subject_common_name": {
          "type": "string",
          "format": "text",
          "description": "certificate subject common name",
          "minLength": 1,
          "maxLength": 255
        },
        "not_before": {
          "type": "string",
          "format": "date-time",
          "description": "certificate validity not before",
          "minLength": 24,
          "maxLength": 24
        },
        "not_after": {
          "type": "string",
          "format": "date-time",
          "description": "certificate validity not after",
          "minLength": 24,
          "maxLength": 24
        },
        "serial": {
          "type": "string",
          "format": "text",
          "description": "serial number",
          "minLength": 1,
          "maxLength": 255
        },
        "version": {
          "type": "integer",
          "format": "int32",
          "description": "version"
        },
        "signature_algorithm": {
          "type": "string",
          "format": "sha-256",
          "description": "certificate signature algorithm",
          "minLength": 1,
          "maxLength": 255
        },
        "signature": {
          "type": "string",
          "format": "text",
          "description": "hex encoded certificate signature",
          "minLength": 1,
          "maxLength": 255
        },
        "public_key_algorithm": {
          "type": "string",
          "format": "sha-256",
          "description": "certificate public key algorithm",
          "minLength": 1,
          "maxLength": 255
        },
        "rsa_public_key_modulus": {
          "type": "string",
          "format": "hex",
          "description": "hex encoded RSA public key modulus (if RSA key)",
          "minLength": 1,
          "maxLength": 1000
        },
        "rsa_public_key_exponent": {
          "type": "integer",
          "format": "int32",
          "description": "RSA public key exponent (if RSA key) as an integer"
        },
        "ec_public_parameters": {
          "description": "EC public key curve (if EC key)",
          "format": "text",
          "maxLength": 255,
          "minLength": 1,
          "type": "string"
        },
        "ec_public_key_point": {
          "description": "hex encoded EC public key point (if EC key)",
          "format": "hex",
          "maxLength": 1000,
          "minLength": 1,
          "type": "string"
        },
        "hash": {
          "type": "string",
          "format": "text",
          "description": "certificate SHA-256 hash",
          "minLength": 1,
          "maxLength": 64
        },
        "key_usages": {
          "type": "array",
          "description": "certificate key usage array",
          "uniqueItems": true,
          "items": {
            "$ref": "#/$defs/KeyUsage"
          }
        },
        "subject_alternative_names": {
          "type": "string",
          "format": "text",
          "description": "certificate subject alternative names",
          "minLength": 1,
          "maxLength": 1000
        }
      }
    },
    "CertificateOcspStatus": {
      "type": "string",
      "description": "certificate status",
      "enum": [
        "DISABLED",
        "EXPIRED",
        "OCSP_RESPONSE_UNKNOWN",
        "OCSP_RESPONSE_GOOD",
        "OCSP_RESPONSE_SUSPENDED",
        "OCSP_RESPONSE_REVOKED"
      ]
    },
    "CertificateStatus": {
      "type": "string",
      "description": "certificate status",
      "enum": [
        "SAVED",
        "REGISTRATION_IN_PROGRESS",
        "REGISTERED",
        "DELETION_IN_PROGRESS",
        "GLOBAL_ERROR"
      ]
    },
    "Key": {
      "type": "object",
      "description": "Key for the certificate. Also includes the possible actions that can be done to this object, e.g DELETE (only for key related operations and does not consider user authorization).",
      "required": [
        "id",
        "name",
        "label",
        "certificates",
        "certificate_signing_requests",
        "key_algorithm"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "text",
          "description": "key id",
          "minLength": 1,
          "readOnly": true
        },
        "name": {
          "type": "string",
          "format": "text",
          "description": "key name",
          "minLength": 1,
          "maxLength": 255
        },
        "label": {
          "type": "string",
          "format": "text",
          "description": "key label",
          "minLength": 1,
          "maxLength": 255
        },
        "certificates": {
          "type": "array",
          "description": "list of certificates for the key",
          "items": {
            "$ref": "#/$defs/TokenCertificate"
          }
        },
        "certificate_signing_requests": {
          "type": "array",
          "description": "list of CSRs for the key",
          "items": {
            "$ref": "#/$defs/TokenCertificateSigningRequest"
          }
        },
        "usage": {
          "$ref": "#/$defs/KeyUsageType"
        },
        "available": {
          "type": "boolean",
          "description": "if the key is available"
        },
        "saved_to_configuration": {
          "type": "boolean",
          "description": "if the key is saved to configuration"
        },
        "possible_actions": {
          "$ref": "#/$defs/PossibleActions"
        },
        "key_algorithm": {
          "$ref": "#/$defs/KeyAlgorithm"
        }
      }
    },
    "KeyAlgorithm": {
      "description": "Key type",
      "enum": [
        "RSA",
        "EC"
      ],
      "type": "string"
    },
    "KeyUsage": {
      "type": "string",
      "description": "certificate key usage",
      "enum": [
        "DIGITAL_SIGNATURE",
        "NON_REPUDIATION",
        "KEY_ENCIPHERMENT",
        "DATA_ENCIPHERMENT",
        "KEY_AGREEMENT",
        "KEY_CERT_SIGN",
        "CRL_SIGN",
        "ENCIPHER_ONLY",
        "DECIPHER_ONLY"
      ]
    },
    "KeyUsageType": {
      "type": "string",
      "description": "intended usage for the key (signing or authentication)",
      "enum": [
        "AUTHENTICATION",
        "SIGNING"
      ]
    },
    "KeyValuePair": {
      "type": "object",
      "description": "key-value pair of strings",
      "required": [
        "key",
        "value"
      ],
      "properties": {
        "key": {
          "type": "string",
          "description": "key"
        },
        "value": {
          "type": "string",
          "description": "value"
        }
      }
    },
    "PossibleAction": {
      "type": "string",
      "description": "an action to change state or edit token, key, cert or csr",
      "enum": [
        "DELETE",
        "ACTIVATE",
        "DISABLE",
        "LOGIN",
        "LOGOUT",
        "REGISTER",
        "UNREGISTER",
        "IMPORT_FROM_TOKEN",
        "GENERATE_KEY",
        "EDIT_FRIENDLY_NAME",
        "GENERATE_AUTH_CSR",
        "GENERATE_SIGN_CSR",
        "TOKEN_CHANGE_PIN",
        "TOKEN_DELETE"
      ]
    },
    "PossibleActions": {
      "type": "array",
      "description": "array containing the possible actions that can be done for this item",
      "items": {
        "$ref": "#/$defs/PossibleAction"
      }
    },
    "TokenCertificate": {
      "type": "object",
      "description": "Certificate that is stored in a Token (auth or sign cert). Also includes the possible actions that can be done to this object, e.g DELETE (only for cert related operations and does not consider user authorization).",
      "required": [
        "ocsp_status",
        "owner_id",
        "active",
        "saved_to_configuration",
        "certificate_details",
        "status"
      ],
      "properties": {
        "ocsp_status": {
          "$ref": "#/$defs/CertificateOcspStatus"
        },
        "owner_id": {
          "type": "string",
          "format": "text",
          "description": "client id of the owner member, <instance_id>:<member_class>:<member_code>",
          "minLength": 1,
          "maxLength": 767,
          "readOnly": true
        },
        "active": {
          "type": "boolean",
          "description": "if the certificate is active"
        },
        "saved_to_configuration": {
          "type": "boolean",
          "description": "if the certificate is saved to configuration"
        },
        "renewed_cert_hash": {
          "type": "string",
          "format": "text",
          "description": "hash of the newer version of the certificate that is in the process of registration",
          "readOnly": true
        },
        "renewal_error": {
          "type": "string",
          "format": "text",
          "description": "error message thrown during the certificate automatic renewal process",
          "readOnly": true
        },
        "ocsp_verify_before_activation_error": {
          "type": "string",
          "format": "text",
          "description": "error message thrown when verifying ocsp responses before the certificate activation",
          "readOnly": true
        },
        "next_automatic_renewal_time": {
          "type": "string",
          "format": "date-time",
          "description": "next planned automatic renewal time",
          "readOnly": true
        },
        "certificate_details": {
          "$ref": "#/$defs/CertificateDetails"
        },
        "status": {
          "$ref": "#/$defs/CertificateStatus"
        },
        "possible_actions": {
          "$ref": "#/$defs/PossibleActions"
        }
      }
    },
    "TokenCertificateSigningRequest": {
      "type": "object",
      "description": "CSR for certificate that is stored in a Token. Also includes the possible actions that can be done to this object, e.g DELETE (only for csr related operations and does not consider user authorization).",
      "required": [
        "id",
        "owner_id",
        "possible_actions"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "text",
          "description": "CSR id",
          "readOnly": true
        },
        "owner_id": {
          "type": "string",
          "format": "text",
          "description": "client id of the owner member, <instance_id>:<member_class>:<member_code>",
          "minLength": 1,
          "maxLength": 767,
          "readOnly": true
        },
        "certificate_profile": {
          "type": "string",
          "format": "text",
          "description": "Fully qualified class name that was used to create the CSR. Implements the ee.ria.xroad.common.certificateprofile.CertificateProfileInfoProvider interface.",
          "readOnly": true
        },
        "possible_actions": {
          "$ref": "#/$defs/PossibleActions"
        }
      }
    },
    "TokenStatus": {
      "type": "string",
      "format": "text",
      "description": "token type",
      "enum": [
        "OK",
        "USER_PIN_LOCKED",
        "USER_PIN_INCORRECT",
        "USER_PIN_INVALID",
        "USER_PIN_EXPIRED",
        "USER_PIN_COUNT_LOW",
        "USER_PIN_FINAL_TRY",
        "NOT_INITIALIZED"
      ]
    },
    "TokenType": {
      "type": "string",
      "format": "text",
      "description": "token type",
      "enum": [
        "SOFTWARE",
        "HARDWARE"
      ]
    }
  }
}