Authentication

Credentials

Ubikap gives you a Synchro Service user:

• a userUuid (a UUIDv7);
• a TOTP secret, to enroll in a TOTP library: it produces 8-digit codes, with SHA-512 and a 30-second period. The codes of the previous and next periods are also accepted, to absorb clock drift.

The user is granted access to the offices that use your software, and to the RPCs listed in your contract. 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.externalId	The office’s id in your software, e.g. 12345. Ubikap stored it when the office was connected to your software.
userUuid	Your Synchro Service user’s UUIDv7.
userCode	The current 8-digit TOTP code.

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

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

Caution

The Synchro Service identifies the office by externalId, the Public API by its Ubikap key. Their LogIn messages are not compatible, and neither are their tokens: a Public API token is refused here, and the other way round.

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 synchronize another office, log in again with that office’s externalId.

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 service — a synchronization to post, a state to poll — rather than keeping a token around. Within a long run, a call that answers UNAUTHENTICATED (401) Your token has expired means it is time to call LogIn again, with a new TOTP code.

Errors

gRPC status	HTTP	Message	Cause
INVALID_ARGUMENT	400	Unable to parse input DTO: …	A missing field, a userUuid that is not a UUIDv7, a userCode that is not 8 digits.
INVALID_ARGUMENT	400	No office with this external id '…' exists	No Ubikap office is connected under this externalId.
INVALID_ARGUMENT	400	User with id '…' not found	Unknown userUuid.
INVALID_ARGUMENT	400	Invalid OTP code	Wrong or expired TOTP code.
PERMISSION_DENIED	403	Action CAN_GET_TOKEN_FOR_OFFICE_SCOPE refused …	Your user has no access to this office.

On the other RPCs:

gRPC status	HTTP	Message	Cause
UNAUTHENTICATED	401	Missing Authorization header	No authorization metadata or header.
UNAUTHENTICATED	401	Your token has expired	Log in again.
UNAUTHENTICATED	401	Unable to verify the signature of the token (token invalid)	The token was altered, or comes from another service or environment.
INVALID_ARGUMENT	400	Invalid Authorization metadata format. Expected "Bearer <token>"	The value is not exactly Bearer <token>.
PERMISSION_DENIED	403	Action CAN_USE_ENDPOINT refused …	Your user is not allowed to call this RPC.