gRPC Authentication

This section describes the gRPC interface of the messaging platform.

The gRPC API provides high-performance access to authentication and SMS messaging functionality. It is intended for internal services and high-throughput clients.

The API exposes two main services:

• Auth Service — user management and authorization (this page)
• SMS Service — message submission and delivery tracking (gRPC Messaging)

gRPC Transport

The gRPC server accepts connections over HTTP/2.

Example endpoint:

127.0.0.1:44044

Authentication

All protected gRPC endpoints require authentication via metadata headers.

The following metadata must be provided with each request:

Example metadata:

authorization: Bearer eyJhbGciOiJIUzI1NiIs...
app_id: 1

Obtaining a Token

Tokens are obtained through the Login RPC:

grpcurl \
  -plaintext \
  -d '{"app_id":1,"email":"admin@example.com","password":"password"}' \
  '127.0.0.1:44044' \
  auth.Auth.Login

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

The token must be included in all subsequent gRPC calls. Tokens expire after the duration configured in security.token_ttl (default: 12 hours).

Testing with grpcurl

The gRPC API can be tested using grpcurl.

Example request with authentication:

grpcurl \
  -plaintext \
  -H 'authorization: Bearer <jwt-token>' \
  -H 'app_id: 1' \
  -emit-defaults \
  -d '{"text":"example message"}' \
  127.0.0.1:44044 \
  sms.v1.SmsService/CheckTextLen

Auth Service

Authentication service responsible for user management and authorization.

Service name:

auth.Auth

Register

Registers a new user account.

rpc Register(RegisterRequest) returns (RegisterResponse)

Request Fields

{
  "email": "user@example.com",
  "password": "secure-password"
}

Response Fields

{
  "user_id": 1
}

Errors

Login

Authenticates a user and returns a JWT token.

rpc Login(LoginRequest) returns (LoginResponse)

Request Fields

{
  "email": "admin@example.com",
  "password": "password",
  "app_id": 1
}

Response Fields

{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

Errors

IsAdmin

Checks whether a user has administrator privileges.

rpc IsAdmin(IsAdminRequest) returns (IsAdminResponse)

Request Fields

{
  "user_id": 1
}

Response Fields

{
  "is_admin": true
}

DeleteUser

Removes a user account from the system.

rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse)

Request Fields

{
  "user_id": 3
}

Response Fields

{
  "result": true
}

Errors

gRPC Error Codes

The platform uses standard gRPC status codes. Common codes across all endpoints:

Error responses include a human-readable message field describing the specific failure.

Service Summary