gRPC API

The gRPC API links and unlinks platform accounts and syncs ephemeral key pools. The RelaySMS app calls it while online.

Protocol buffer file

curl -O -L https://raw.githubusercontent.com/smswithoutborders/RelaySMS-Publisher/main/protos/v3/publisher.proto

Package publisher.v3, service Publisher.

Generate a client

Generate stubs with protoc for your language. For Python:

pip install grpcio-tools
python -m grpc_tools.protoc -I . --python_out=. --grpc_python_out=. publisher.proto

Request headers

Every RPC needs these headers. Headers ending in -bin carry raw binary.

The examples use -plaintext against a local server; drop it for a server behind TLS on port 443.

Methods

Get OAuth2 authorization URL

Returns the URL that starts the OAuth2 flow.

Request: GetOAuth2AuthorizationUrlRequest

Response: GetOAuth2AuthorizationUrlResponse

Example:

grpcurl -plaintext \
  -H 'x-payload-bin: <ENCRYPTED_PAYLOAD>' \
  -H 'x-public-key-bin: <CLIENT_PUBLIC_KEY>' \
  -H 'x-key-id: <KEY_ID>' \
  -H 'x-nonce-bin: <NONCE>' \
  -H 'x-timestamp: <TIMESTAMP>' \
  -d '{
    "platform": "gmail",
    "autogenerate_code_verifier": true
  }' \
  -proto publisher.proto \
  <HOST>:<PORT> publisher.v3.Publisher/GetOAuth2AuthorizationUrl

Exchange OAuth2 code and store token

Exchanges an OAuth2 authorization code for tokens and stores them. Returns encrypted token data and a set of server ephemeral keys.

Request: ExchangeOAuth2CodeAndStoreRequest

PublicKey message:

Response: ExchangeOAuth2CodeAndStoreResponse

Example:

grpcurl -plaintext \
  -H 'x-payload-bin: <ENCRYPTED_PAYLOAD>' \
  -H 'x-public-key-bin: <CLIENT_PUBLIC_KEY>' \
  -H 'x-key-id: <KEY_ID>' \
  -H 'x-nonce-bin: <NONCE>' \
  -H 'x-timestamp: <TIMESTAMP>' \
  -d @ \
  -proto publisher.proto \
  <HOST>:<PORT> publisher.v3.Publisher/ExchangeOAuth2CodeAndStore <<EOF
{
  "platform": "gmail",
  "authorization_code": "auth_code",
  "client_ephemeral_public_keys": [
    {"key_id": 0, "public_key": "..."},
    ... 254 more keys ...
    {"key_id": 255, "public_key": "..."}
  ]
}
EOF

Revoke and delete OAuth2 token

Revokes and deletes a stored OAuth2 token, identified by its token ID and the key ID that encrypted it.

Request: RevokeOAuth2TokenRequest

Response: RevokeOAuth2TokenResponse

Example:

grpcurl -plaintext \
  -H 'x-payload-bin: <ENCRYPTED_PAYLOAD>' \
  -H 'x-public-key-bin: <CLIENT_PUBLIC_KEY>' \
  -H 'x-key-id: <KEY_ID>' \
  -H 'x-nonce-bin: <NONCE>' \
  -H 'x-timestamp: <TIMESTAMP>' \
  -d '{
    "token_id": 2941967295,
    "key_id": 123
  }' \
  -proto publisher.proto \
  <HOST>:<PORT> publisher.v3.Publisher/RevokeOAuth2Token

Get PNBA code

Requests a one-time passcode (OTP) for phone number-based authentication (PNBA).

Request: GetPNBACodeRequest

Response: GetPNBACodeResponse

Example:

grpcurl -plaintext \
  -H 'x-payload-bin: <ENCRYPTED_PAYLOAD>' \
  -H 'x-public-key-bin: <CLIENT_PUBLIC_KEY>' \
  -H 'x-key-id: <KEY_ID>' \
  -H 'x-nonce-bin: <NONCE>' \
  -H 'x-timestamp: <TIMESTAMP>' \
  -d '{
    "platform": "telegram",
    "phone_number": "+237600000000"
  }' \
  -proto publisher.proto \
  <HOST>:<PORT> publisher.v3.Publisher/GetPNBACode

Exchange PNBA code and store token

Exchanges a one-time passcode (OTP) for a token, stores it, and returns encrypted token data.

Request: ExchangePNBACodeAndStoreRequest

Response: ExchangePNBACodeAndStoreResponse

Example:

grpcurl -plaintext \
  -H 'x-payload-bin: <ENCRYPTED_PAYLOAD>' \
  -H 'x-public-key-bin: <CLIENT_PUBLIC_KEY>' \
  -H 'x-key-id: <KEY_ID>' \
  -H 'x-nonce-bin: <NONCE>' \
  -H 'x-timestamp: <TIMESTAMP>' \
  -d @ \
  -proto publisher.proto \
  <HOST>:<PORT> publisher.v3.Publisher/ExchangePNBACodeAndStore <<EOF
{
  "platform": "telegram",
  "phone_number": "+237600000000",
  "authorization_code": "auth_code",
  "client_ephemeral_public_keys": [
    {"key_id": 0, "public_key": "..."},
    ... 254 more keys ...
    {"key_id": 255, "public_key": "..."}
  ]
}
EOF

Revoke and delete PNBA token

Revokes and deletes a stored PNBA token.

Request: RevokePNBATokenRequest

Response: RevokePNBATokenResponse

Example:

grpcurl -plaintext \
  -H 'x-payload-bin: <ENCRYPTED_PAYLOAD>' \
  -H 'x-public-key-bin: <CLIENT_PUBLIC_KEY>' \
  -H 'x-key-id: <KEY_ID>' \
  -H 'x-nonce-bin: <NONCE>' \
  -H 'x-timestamp: <TIMESTAMP>' \
  -d '{
    "token_id": 2941967295,
    "key_id": 123
  }' \
  -proto publisher.proto \
  <HOST>:<PORT> publisher.v3.Publisher/RevokePNBAToken

Sync keys

Replaces a token’s key pools: the client sends 256 new ephemeral public keys and the server returns 256 of its own.

Request: SyncKeysRequest

Response: SyncKeysResponse

Example:

grpcurl -plaintext \
  -H 'x-payload-bin: <ENCRYPTED_PAYLOAD>' \
  -H 'x-public-key-bin: <CLIENT_PUBLIC_KEY>' \
  -H 'x-key-id: <KEY_ID>' \
  -H 'x-nonce-bin: <NONCE>' \
  -H 'x-timestamp: <TIMESTAMP>' \
  -d @ \
  -proto publisher.proto \
  <HOST>:<PORT> publisher.v3.Publisher/SyncKeys <<EOF
{
  "token_id": 2941967295,
  "key_id": 123,
  "client_ephemeral_public_keys": [
    {"key_id": 0, "public_key": "..."},
    ... 254 more keys ...
    {"key_id": 255, "public_key": "..."}
  ]
}
EOF

Every RPC returns a standard gRPC status code; 0 OK is success.