Public API authentication

Credentials

Ubikap gives you a Public API user:

• a userUuid (a UUIDv7);
• a TOTP secret, to enroll in an authenticator application or a TOTP library: it produces 8-digit codes.

The user is granted access to one or more offices. A token is always issued for one office.

Get a token

Call AuthenticationService.LogIn (REST: POST /services.authentication.v1.AuthenticationService/LogIn). It needs no token.

Field	Description
officeScope.target.office.key	Key of the office to act on, e.g. OFC_1234.
userUuid	Your Public API user’s UUIDv7.
userCode	The current 8-digit TOTP code.

{
  "officeScope": { "target": { "office": { "key": "OFC_1234" } } },
  "userUuid": "01920000-0000-7000-8000-000000000000",
  "userCode": "12345678"
}

The response is { "token": "<jwt>" }.

The proto also declares officeUserScope and partnershipScope, but no RPC accepts their tokens yet: use officeScope.

Use the token

Send the token on every other call:

• gRPC: metadata authorization: Bearer <token>;
• REST: header Authorization: Bearer <token>.

The token only gives access to the office it was issued for. To work on another office, log in again with that office’s key.

Expiry and renewal

The token expires 30 minutes after it was issued, and there is no refresh RPC.

Log in again each time you start working with the API, rather than keeping a token around. Within a long run, a call that answers UNAUTHENTICATED (401) means it is time to call LogIn again, with a new TOTP code.

Errors

Status	Message	Cause
401	Missing Authorization header	No Authorization header or metadata.
400	—	The header is not exactly Bearer <token>.
400	Invalid OTP code	Wrong or expired TOTP code.
400	User with id '…' not found	Unknown userUuid.
403	—	Your user has no access to the requested office.

Not an OIDC token

The Public API token is unrelated to the OIDC provider: the Public API refuses OIDC access tokens, and the OIDC provider knows nothing about Public API users.