Skip to main content

OKM API Tokens

API tokens are used in the exchanges between the OKM Service and OKMs, to control which OKMs are authorized to query the service. The purpose of the token is to indicate that an OKM is authorized to make requests to an OKM Service instance.

These are separate from the JWT access tokens used by implementers. See JWT Authentication for the resource endpoints.

Endpoints using this mechanism​

  1. /config/{serial_number}
  2. /audit/{serial_number}

An OKM that is unknown to the service, or whose token is missing or invalid, will not be served by these endpoints.

Exchange Flow Summary​

This is how the initial token attribution flow happens, in short. At this time, there is no UI implemented for a person to manually “allocate” the token for an OKM. So for now, the token is flagged as claimed when it’s first attributed to the OKM.

  1. OKM calls the OKM service.
  2. The service looks into its DB for the OKM.
  3. OKM not found.
  4. OKM is added to service-application (via portal most likely).
  5. OKM create request is sent to OKM Service.
  6. OKM service generates API Token for this OKM.
  7. Token claimed flag is false.
  8. User adds tags to OKM in service-application:
    1. this triggers the generation of an ACL;
    2. ACL create request is sent to OKM service.
  9. OKM connects again.
  10. Service looks in DB and finds OKM has an ACL and has an unclaimed token.
  11. Service returns msg_Token_e response to OKM with token.
  12. OKM connects again with an Authorization: Bearer <token> in its request header.
  13. Service compares bearer token with token in database.
    1. If token is not the correct one, a 401 - Unauthorized is returned.
    2. If token is good, service marks token as claimed and processing continues down the stack.

This OKM can now make requests to this OKM service instance. All requests from now on will require the token. If the token is not present or doesn’t match what’s stored in the server, the request is denied.

Note A firmware update will erase the token from the OKM memory. Once the OKM reconnects after a firmware update, a new API access token needs to be obtained.

Managing a token​

A token is issued per OKM and is tracked as claimed or unclaimed. Two endpoints on the OKM resource manage its lifecycle:

Both are useful when doing a factory reset of an OKM without deleting it from the system, and then connecting it again to the same system.