gRPC

The Public API is a gRPC server first: the REST gateway translates each HTTP call into the same RPC. Calling gRPC directly gives you typed clients generated from our .proto files.

Endpoint


Address	`public.api.external-integration.ubikap.dev:443`, IPv4 and IPv6
Transport	HTTP/2 over TLS — plaintext is not accepted

gRPC and REST share the same host and port. Each request is routed on its content-type header:

`content-type`	Routed to
Starts with `application/grpc` (`application/grpc`, `application/grpc+proto`)	The gRPC server
Anything else (`application/json`, none)	The REST gateway

Every gRPC library sets application/grpc by itself. Two consequences:

gRPC-Web is not supported. Its application/grpc-web content type is routed to the gRPC server, which does not speak gRPC-Web: call the REST gateway from a browser instead.
A REST call must not send an application/grpc… content type, or it reaches the gRPC server and fails.

Proto files

Download the .proto files. The archive holds:

services/<service>/v1/<service>_service.proto, one file per service, in the package services.<service>.v1;
buf.yaml and buf.lock, which pin the two imported dependencies: google/api/annotations.proto (googleapis) and buf/validate/validate.proto (protovalidate).

With buf, buf generate resolves those dependencies by itself: see Getting Started for a TypeScript client. The archive is rebuilt with every release of these docs; download it again when the changelog announces a change.

Server reflection

The server implements gRPC server reflection, under both grpc.reflection.v1 and grpc.reflection.v1alpha. Tools such as grpcurl and Postman can list the services, describe the messages and build requests without the .proto files. Only the public services are listed.

Authentication

Call services.authentication.v1.AuthenticationService/LogIn first — it needs no credentials — then send the token it returns in the metadata of every other call:

authorization: Bearer <token>

See Public API authentication for the login fields and the token’s scope.

Status codes

Errors carry a gRPC status code and a message describing the problem. The REST gateway answers the matching HTTP status.

gRPC status	Code	HTTP (REST)	Typical cause
`INVALID_ARGUMENT`	3	400	Invalid input, wrong TOTP code, upload not found or not a PDF.
`UNAUTHENTICATED`	16	401	Missing or expired token.
`PERMISSION_DENIED`	7	403	The token’s office does not give access to the resource.
`NOT_FOUND`	5	404	The requested resource does not exist.
`INTERNAL`	13	500	Unexpected server error: retry later, contact us if it persists.
`CANCELLED`	1	499	The client cancelled the call or its deadline expired.
`UNKNOWN`	2	500	Any other error.

Set a deadline on every call, so that a stalled call fails with DEADLINE_EXCEEDED on your side instead of hanging.

Messages

Messages are proto3. Through the REST gateway, the same messages are JSON with camelCase field names (user_uuid becomes userUuid) and enums as their names ("REGISTER_ITEM_MINUTES").

Recipes: Call the API with grpcurl or Postman.