Reference

Security elements

Safe certificate metadata (JID, validity, status) without secrets. For monitoring expiry and environment.

2 operations

List security elements

get/v1/security-elements

Scope security-elements:read

Certificate metadata per taxpayer and premise: JID, environment, validity, expiry status and replacement recommendation. Secrets are never returned.

Contract notes (OpenAPI)

Secret envelope references and plaintext values are never returned. Scoped to the caller's environment like every other tenant read.

Parameters

listSecurityElements: Parameters
Field	In	Type	Description
`taxpayerId`optional	query	uuid
`businessPremiseId`optional	query	uuid

Example

GET /v1/security-elements

curl -X GET "https://api.bokapos.rs/v1/security-elements?businessPremiseId=b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

Responses

listSecurityElements: Responses
200 OK	Tenant-scoped security elements

200 OK

{
  "items": [
    {
      "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a80",
      "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
      "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
      "environment": "sandbox",
      "jid": "JWX4K9PL",
      "certificateThumbprint": "A1B2C3D4E5F60718293A4B5C6D7E8F9012345678",
      "certificateSubject": "CN=JWX4K9PL, O=BOKA GROUP DOO, C=RS",
      "certificateIssuer": "CN=Sandbox ICA, O=Poreska uprava Republike Srbije, C=RS",
      "certificateSerialNumber": "3F9C2A8E6B1D",
      "certificateNotBefore": "2026-08-20T00:00:00Z",
      "certificateNotAfter": "2028-08-20T00:00:00Z",
      "certificateExpiryStatus": "current",
      "replacementRecommended": false,
      "status": "active",
      "createdAt": "2026-08-21T09:10:00.000Z",
      "updatedAt": "2026-08-21T09:12:00.000Z"
    }
  ]
}

Response:

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

listSecurityElements: Response
Field	Type	Description
`items`required	array<SecurityElement>
`id`required	uuid
`taxpayerId`required	uuid
`businessPremiseId`required	uuid
`environment`required	FiscalEnvironment	The Stripe-style fiscal environment. Machine credentials carry exactly one environment and may only use security elements of that environment; sandbox elements are BOKA-assigned and route to the TaxCore sandbox, production elements are the customer's own. Taxpayers and business premises carry the environment too: the BOKA sandbox taxpayer and premise created by a pool assignment are sandbox, everything a human registers is production, and setup registered by a machine credential belongs to that credential's environment. A premise inherits its taxpayer's environment and a security element can only be bound to a premise of its own. `sandboxproduction`Values
`jid`required	string
`certificateThumbprint`required	string
`certificateSubject`required	string
`certificateIssuer`required	string
`certificateSerialNumber`required	string
`certificateNotBefore`required	date-time
`certificateNotAfter`required	date-time
`certificateExpiryStatus`required	string	Server-evaluated public-certificate time status using the configured 30-day warning and 7-day critical windows by default. `not-yet-validcurrentwarningcriticalexpired`Values
`replacementRecommended`required	boolean	True for a non-retired element whose public certificate is inside the warning window or expired; this is not proof of revocation or V-PFR status.
`status`required	string	`pending-verificationactivesuspendedretired`Values
`createdAt`required	date-time
`updatedAt`required	date-time

Read a security element

get/v1/security-elements/{securityElementId}

Scope security-elements:read

One element by identifier, the same safe set of fields.

Parameters

getSecurityElement: Parameters
Field	In	Type	Description
`securityElementId`required	path	uuid

Example

GET /v1/security-elements/{securityElementId}

curl -X GET "https://api.bokapos.rs/v1/security-elements/e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a80" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

Responses

getSecurityElement: Responses
200 OK	Security element metadata`SecurityElement`
404 Not Found	Resource does not exist within the authenticated tenant scope`ErrorCode`

200 OK

{
  "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a80",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "environment": "sandbox",
  "jid": "JWX4K9PL",
  "certificateThumbprint": "A1B2C3D4E5F60718293A4B5C6D7E8F9012345678",
  "certificateSubject": "CN=JWX4K9PL, O=BOKA GROUP DOO, C=RS",
  "certificateIssuer": "CN=Sandbox ICA, O=Poreska uprava Republike Srbije, C=RS",
  "certificateSerialNumber": "3F9C2A8E6B1D",
  "certificateNotBefore": "2026-08-20T00:00:00Z",
  "certificateNotAfter": "2028-08-20T00:00:00Z",
  "certificateExpiryStatus": "current",
  "replacementRecommended": false,
  "status": "active",
  "createdAt": "2026-08-21T09:10:00.000Z",
  "updatedAt": "2026-08-21T09:12:00.000Z"
}

Response: SecurityElement

Field descriptions come from the OpenAPI contract; field names and values are identical in both languages.

getSecurityElement: Response
Field	Type	Description
`id`required	uuid
`taxpayerId`required	uuid
`businessPremiseId`required	uuid
`environment`required	FiscalEnvironment	The Stripe-style fiscal environment. Machine credentials carry exactly one environment and may only use security elements of that environment; sandbox elements are BOKA-assigned and route to the TaxCore sandbox, production elements are the customer's own. Taxpayers and business premises carry the environment too: the BOKA sandbox taxpayer and premise created by a pool assignment are sandbox, everything a human registers is production, and setup registered by a machine credential belongs to that credential's environment. A premise inherits its taxpayer's environment and a security element can only be bound to a premise of its own. `sandboxproduction`Values
`jid`required	string
`certificateThumbprint`required	string
`certificateSubject`required	string
`certificateIssuer`required	string
`certificateSerialNumber`required	string
`certificateNotBefore`required	date-time
`certificateNotAfter`required	date-time
`certificateExpiryStatus`required	string	Server-evaluated public-certificate time status using the configured 30-day warning and 7-day critical windows by default. `not-yet-validcurrentwarningcriticalexpired`Values
`replacementRecommended`required	boolean	True for a non-retired element whose public certificate is inside the warning window or expired; this is not proof of revocation or V-PFR status.
`status`required	string	`pending-verificationactivesuspendedretired`Values
`createdAt`required	date-time
`updatedAt`required	date-time