JWT Authentication and Authorization

The four resources of the OKM Service — OKM, ACL, ACL-OKM, and Firmware — require a valid JWT access token.

• Authentication verifies the calling service identity by validating the JWT signature, issuer, audience, and expiration.
• Authorization checks whether the authenticated service has the permissions required to access a specific resource.

A single, long-lived shared token authenticates the calling service.

Token Structure

A token carrying full access to every resource looks like this:

{
  "sub": "service-application",
  "iss": "invue",
  "aud": "retail",
  "context": {
    "service-okm": {
      "okms": ["read", "create", "update", "delete"],
      "acls": ["read", "create", "update", "delete"],
      "acl-okms": ["read", "create", "update", "delete"],
      "firmware": ["read", "create", "update", "delete"]
    }
  },
  "iat": 1759779452,
  "exp": 2075355452
}

Permissions are expressed as service-okm:resource:action. Each resource page in this section shows the context object required for each verb.

Protected Endpoints

OKM Management

Method	Endpoint	Permission Required
GET	/api/v1/okms	service-okm:okms:read
GET	/api/v1/okms/:id	service-okm:okms:read
POST	/api/v1/okms	service-okm:okms:create
PUT	/api/v1/okms/:id	service-okm:okms:update
DELETE	/api/v1/okms/:id	service-okm:okms:delete
POST	/api/v1/okms/:id/clear	service-okm:okms:update
POST	/api/v1/okms/:id/token/refresh	service-okm:okms:update
POST	/api/v1/okms/:id/token/clear	service-okm:okms:update

Access Control Lists

Method	Endpoint	Permission Required
GET	/api/v1/acls	service-okm:acls:read
GET	/api/v1/acls/:id	service-okm:acls:read
POST	/api/v1/acls	service-okm:acls:create
PUT	/api/v1/acls/:id	service-okm:acls:update
DELETE	/api/v1/acls/:id	service-okm:acls:delete

ACL-OKM Links

Method	Endpoint	Permission Required
GET	/api/v1/acl-okms	service-okm:acl-okms:read
GET	/api/v1/acl-okms/:okm_id	service-okm:acl-okms:read
POST	/api/v1/acl-okms	service-okm:acl-okms:create
PUT	/api/v1/acl-okms	service-okm:acl-okms:update
DELETE	/api/v1/acl-okms/:okm_id	service-okm:acl-okms:delete

Firmware Management

Method	Endpoint	Permission Required
GET	/api/v1/firmware	service-okm:firmware:read
GET	/api/v1/firmware/:id	service-okm:firmware:read
POST	/api/v1/firmware	service-okm:firmware:create
PUT	/api/v1/firmware/:id	service-okm:firmware:update
DELETE	/api/v1/firmware/:id	service-okm:firmware:delete

Errors

Error	Type	Solution
401 Unauthorized	Authentication	The token is missing, malformed, expired, or signed with a key the service does not recognize.
403 Forbidden	Authorization	The token is valid but does not include the required permission in the service-okm:resource:action format.

Note: The /config and /audit endpoints that OKM devices call do not use JWT. They are protected by a per-device token instead. See OKM API Tokens.