Identity, licences & landing
Sign-in, sessions, two-factor enrolment, service-account keys, licence validation and the
landing dashboard. IdentityService is where every client starts: Login is one of only two
RPCs on the whole API that take no bearer token (the other is
ActivationService/ValidateLicense). See the API overview
for how the token is carried.
Summary
| Service | RPC | Kind | Purpose |
|---|---|---|---|
| IdentityService | Login | Unary | Exchange credentials, a TOTP code or an OIDC ID token for a session token |
| IdentityService | Logout | Unary | End every session of the calling account |
| IdentityService | DeleteAccount | Unary | Delete the caller’s own account, after a typed confirmation |
| IdentityService | EnrollTotp | Unary | Generate a TOTP secret to enrol |
| IdentityService | ConfirmTotp | Unary | Prove the authenticator works and turn two-factor on |
| IdentityService | UpdateUser | Unary | Change an account’s email, role or password |
| IdentityService | CreateInstance | Unary | Acknowledge an instance request (provisions nothing) |
| IdentityService | GenerateServiceAccountKey | Unary | Mint a service-account token for the caller’s tenant |
| ActivationService | ValidateLicense | Unary | Check a signed licence key |
| LandingService | GetDashboardStats | Unary | Live dashboard counters for the caller’s instance |
IdentityService
Full name semantics.v1.IdentityService.
This service handles authentication and account management for one FACE deployment. Membership and roles of an instance are managed through the platform’s shared Admin page, not through this service: it has no RPC that adds or deletes another user. A person deletes only their own account, with DeleteAccount.
Login
rpc Login(LoginRequest) returns (LoginResponse);- Kind: Unary.
- Auth: None. This RPC is exempt from bearer authentication.
- Errors:
INTERNALif the server cannot issue a session or start the MFA step, or cannot provision the local account for a first-time SSO user. An ordinary sign-in failure is not a gRPC error. The call succeeds withstatus: STATUS_FAILUREand a human-readablemessage.
Login is a one-step or two-step exchange, selected by method:
method | Required fields | Outcome |
|---|---|---|
AUTH_METHOD_CREDENTIALS | username (the account email), password; captcha_token when the deployment enforces reCAPTCHA | STATUS_SUCCESS with token, or STATUS_MFA_REQUIRED with mfa_session if the account has TOTP enabled |
AUTH_METHOD_MFA_VERIFY | mfa_session (from the previous response), mfa_code (6-digit TOTP) | STATUS_SUCCESS with token |
AUTH_METHOD_GOOGLE_OIDC | oidc_token (an OIDC ID token from the deployment’s configured issuer); captcha_token when the deployment enforces reCAPTCHA | STATUS_SUCCESS with token |
Behaviour worth knowing:
- Session lifetime. A session token is valid for 12 hours unless it is revoked first. Revocation (logout, or an admin changing the account) takes effect on every replica.
- MFA window. The
mfa_sessionfrom aSTATUS_MFA_REQUIREDresponse expires after 5 minutes. After that the MFA step fails with “MFA session expired” and the client must sign in again. - SSO-only deployments. A deployment can be locked to SSO. Password sign-in then fails with “Password sign-in is disabled”.
- OIDC. The ID token must verify against the configured issuer and carry a verified email. That email must also be on the deployment’s allowlist. If SSO is configured and the allowlist is empty, nobody can sign in through SSO. A first-time SSO user gets a local account with the Reader role.
- Tenant. Sessions issued by
Loginare bound to the deployment’s default tenant. Handlers scope all reads and writes to the tenant in the verified session, never to a tenant named in a request.
Failure message values include Invalid credentials, Captcha verification failed,
Invalid two-factor code, SSO is not configured, SSO verification failed,
This account is not authorized for this instance and Unsupported authentication method.
Request: LoginRequest
| Field | Type | Description |
|---|---|---|
method | LoginRequest.AuthMethod | Which sign-in step this is. |
username | string | Account email, for AUTH_METHOD_CREDENTIALS. |
password | string | Account password, for AUTH_METHOD_CREDENTIALS. |
captcha_token | string | reCAPTCHA v3 token for the login action, for AUTH_METHOD_CREDENTIALS and AUTH_METHOD_GOOGLE_OIDC. Checked (score, action and hostname) only when the deployment sets FACE_RECAPTCHA_*; a missing or failing token then gets Captcha verification failed. FACE’s own deployment does not enforce reCAPTCHA (owner, 2026-11-02), so the field is not checked there. Field 5, formerly hcaptcha_token. |
oidc_token | string | OIDC ID token, for AUTH_METHOD_GOOGLE_OIDC. |
mfa_code | string | 6-digit TOTP code, for AUTH_METHOD_MFA_VERIFY. |
mfa_session | string | The mfa_session returned by the credentials step, for AUTH_METHOD_MFA_VERIFY. |
Reserved: field 2 (key).
Response: LoginResponse
| Field | Type | Description |
|---|---|---|
status | LoginResponse.Status | Outcome of this step. |
token | string | The session token (a signed JWT) on STATUS_SUCCESS. Send it as authorization: Bearer <token>. |
message | string | Human-readable outcome, safe to show to the user. |
mfa_session | string | Short-lived challenge to send back with AUTH_METHOD_MFA_VERIFY, on STATUS_MFA_REQUIRED. |
Logout
rpc Logout(LogoutRequest) returns (LogoutResponse);- Kind: Unary.
- Auth: Bearer session.
- Errors:
UNAUTHENTICATEDif the session carries no subject.INTERNALif the sessions could not be revoked. In that case nothing was revoked.
Revokes every session of the calling account, not only the one making the call. The
account is taken from the authenticated session. The token field in the request is accepted
for wire compatibility and is ignored, so one caller cannot end another account’s sessions.
Request: LogoutRequest
| Field | Type | Description |
|---|---|---|
token | string | Ignored. The session revoked is the one authenticating the call. |
Response: LogoutResponse
| Field | Type | Description |
|---|---|---|
success | bool | true once the sessions are revoked. |
DeleteAccount
rpc DeleteAccount(DeleteAccountRequest) returns (DeleteAccountResponse);- Kind: Unary.
- Auth: Bearer session, any role. Service-account tokens are refused.
- Errors:
UNAUTHENTICATEDwith no verified session.PERMISSION_DENIEDfor a service account.INVALID_ARGUMENTwhenconfirm_emailis not the caller’s own address.FAILED_PRECONDITIONwhen the caller is the last organisation admin, or the deployment’s break-glass admin, or the session carries no email.UNAVAILABLEwhen the accounts could not be read.INTERNALwhen a step failed. In every case the account is not reported deleted.
Deletes the caller’s own account, as Google Play requires of an app that creates accounts. The account is the one the verified session names, never a field of the request, and the request holds no way to name another. The typed confirmation, the caller’s own email address, is compared case-insensitively with the email of the verified session.
Deleted: the account record, every session, the follow-up flows the person owns with their
runs, chat and proposals, their scenario-builder scenarios, items and terms, their pending
mailbox connects and the brief suggestions they dismissed. Retained, because it is the organisation’s: briefs, personas, connections,
schedules, the run history, the mailbox the organisation connected, follow-up tasks, the audit
log and the decision records. The person’s account number inside retained records is replaced by
the pseudonym former-member- plus ten hex characters (a hash of the account number, the same
one the audit stream uses for an actor). The decision log’s chain is not rewritten: its stored
entries keep the opaque account number, and the pseudonym is applied where the log is served.
The access list is not edited: a later sign-in with a still-listed address creates a new, empty
account. One audit entry (ACCOUNT_DELETED: the hashed actor, the classes of data deleted and
retained, no content) is written once. The call is idempotent: every session ends first, then the
person’s data goes, then the account record last, so after a failed call the person signs in again
and repeats it; a repeat after success returns already_deleted: true. Earlier encrypted versions
of the deleted records stay in storage history until it is compacted and cleaned:
storage_status is scheduled until the store’s erase service has purged them and read back
nothing, and never complete before. The in-app path is described in
Delete your account.
Request: DeleteAccountRequest
| Field | Type | Description |
|---|---|---|
confirm_email | string | The caller’s own email address, typed by the person. |
Response: DeleteAccountResponse
| Field | Type | Description |
|---|---|---|
deleted | bool | true once the account no longer exists and its sessions are ended. |
already_deleted | bool | true when the account was already gone (a repeat after success). |
deleted_classes | repeated string | The classes of data deleted. |
retained_classes | repeated string | The classes the organisation retains. |
pseudonym | string | The code that stands for the person in retained records. |
storage_status | string | scheduled while earlier encrypted versions may remain in storage history; complete only after the erase service’s read-back listed nothing. |
storage_scheduled_until | string | RFC 3339 time by which those versions are due to be gone: the deletion’s start plus 24 hours. |
EnrollTotp
rpc EnrollTotp(EnrollTotpRequest) returns (EnrollTotpResponse);- Kind: Unary.
- Auth: Bearer session. A caller may enrol their own account, and an org admin may enrol any account.
- Errors:
PERMISSION_DENIEDif the email is not the caller’s own account and the caller is not an org admin. An email that does not exist gets the same error, so the RPC cannot be used to test whether an account exists.INTERNALif the secret cannot be generated.
Generates a fresh TOTP secret and an otpauth:// provisioning URI (issuer FACE). Nothing is
stored until ConfirmTotp succeeds. Returns success: false with
User not found when the account disappears between the permission check and the lookup.
Request: EnrollTotpRequest
| Field | Type | Description |
|---|---|---|
email | string | Email of the account to enrol. |
Response: EnrollTotpResponse
| Field | Type | Description |
|---|---|---|
success | bool | Whether a secret was generated. |
secret | string | Base32 shared secret. Keep it for ConfirmTotp. |
provisioning_uri | string | otpauth:// URI, usually rendered as a QR code. |
message | string | Human-readable outcome. |
ConfirmTotp
rpc ConfirmTotp(ConfirmTotpRequest) returns (ConfirmTotpResponse);- Kind: Unary.
- Auth: Bearer session. Same rule as
EnrollTotp: the caller’s own account, or any account for an org admin. - Errors:
PERMISSION_DENIEDunder the same conditions asEnrollTotp.INTERNALif the secret cannot be saved.
Checks code against secret. On a match, the server stores the secret and turns on two-factor
sign-in for the account. A wrong code returns success: false with
Invalid code — please try again.
Request: ConfirmTotpRequest
| Field | Type | Description |
|---|---|---|
email | string | Email of the account being enrolled. |
secret | string | The secret returned by EnrollTotp. |
code | string | Current 6-digit code from the authenticator app. |
Response: ConfirmTotpResponse
| Field | Type | Description |
|---|---|---|
success | bool | true once two-factor is enabled. |
message | string | Human-readable outcome. |
UpdateUser
rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);- Kind: Unary.
- Auth: Bearer session, org admin only. Service-account tokens are refused.
- Errors:
PERMISSION_DENIEDfor any role other than org admin.INTERNALif the change was saved but the account’s existing sessions could not be ended.
Updates the non-empty fields among email, role and password on the account identified
by user_id. After a successful change, every existing session of that account is revoked, so
the new role or password applies at the next sign-in. Some failures return success: false
with a message instead of an error: UserID required, No such user,
That email is already in use and Update failed.
Request: UpdateUserRequest
| Field | Type | Description |
|---|---|---|
user_id | string | Required. The account to change. |
email | string | New email. Empty leaves it unchanged. |
role | string | New role. Empty leaves it unchanged. |
password | string | New password. Empty leaves it unchanged. |
is_active | bool | Not applied. The account model has no active or disabled state. When true, the response message says the flag was not applied. To disable an account, remove it on the Admin page. |
Response: UpdateUserResponse
| Field | Type | Description |
|---|---|---|
success | bool | Whether the change was applied. |
message | string | Human-readable outcome. |
CreateInstance
rpc CreateInstance(CreateInstanceRequest) returns (CreateInstanceResponse);- Kind: Unary.
- Auth: Bearer session, org admin only. Service-account tokens are refused.
- Errors: None beyond authentication.
Echoes the requested id back with success: true and records nothing. Instances are
provisioned by the platform, not through this RPC.
Request: CreateInstanceRequest
| Field | Type | Description |
|---|---|---|
id | string | Requested instance id, for example org-example-prod. |
name | string | Display name, for example Production Environment. |
Reserved: field 1 (license_key).
Response: CreateInstanceResponse
| Field | Type | Description |
|---|---|---|
success | bool | Always true. |
instance_id | string | The id from the request. |
message | string | Human-readable outcome. |
GenerateServiceAccountKey
rpc GenerateServiceAccountKey(GenerateServiceAccountKeyRequest) returns (GenerateServiceAccountKeyResponse);- Kind: Unary.
- Auth: Bearer session, org admin only. Service-account tokens are refused.
- Errors:
INVALID_ARGUMENTifnameis empty or is a name reserved for an internal credential.PERMISSION_DENIEDif the caller is not an org admin, if the session has no verified tenant, or iftenant_idnames a tenant other than the caller’s.INTERNALif the token cannot be issued.
Mints a signed service-account token with ROLE_SERVICE_ACCOUNT. The token is scoped to the
caller’s own tenant and valid for 365 days. Use it as a bearer token for machine clients
such as runners and integrations. What a service account may call is listed under
Roles. The key is returned once. Store it as a
secret.
Request: GenerateServiceAccountKeyRequest
| Field | Type | Description |
|---|---|---|
tenant_id | string | Optional. If set, it must equal the caller’s own tenant. The server never issues a key for another tenant. |
name | string | Required. Service-account name. The account id becomes sa-<name>. |
Response: GenerateServiceAccountKeyResponse
| Field | Type | Description |
|---|---|---|
api_key | string | The bearer token. Shown once. |
account | ServiceAccount | The account the key belongs to. |
ActivationService
Full name semantics.v1.ActivationService.
Licences are Ed25519-signed documents issued offline by the platform. FACE only verifies them
and never signs one. When a deployment has a licence configured, every authenticated call checks
it. An expired or invalid licence makes every call fail with PERMISSION_DENIED
(license expired or invalid). Service-account tokens are refused on this whole service.
ValidateLicense
rpc ValidateLicense(ValidateLicenseRequest) returns (ValidateLicenseResponse);- Kind: Unary.
- Auth: None. This RPC is exempt from bearer authentication.
- Errors: None. An unverifiable key returns
valid: false.
Returns valid: true only when the deployment has a licence verification key configured,
license_key carries a signature that verifies against it, and the current time is inside the
licence’s validity window. The key may be the signed licence JSON or that JSON base64-encoded.
The server logs only a hash of the key.
Request: ValidateLicenseRequest
| Field | Type | Description |
|---|---|---|
license_key | string | The signed licence, as JSON or base64-encoded JSON. |
Response: ValidateLicenseResponse
| Field | Type | Description |
|---|---|---|
valid | bool | Signature verified and within the validity window. |
customer_email | string | Not populated by the server. |
expires_at | string | Not populated by the server. |
remaining_days | int32 | Not populated by the server. |
subscription | string | Not populated by the server. |
LandingService
Full name semantics.v1.LandingService.
Headline figures for the landing page. GetDashboardStats requires a bearer session. The landing dashboard
shows a customer’s operational data, so it is not readable before sign-in.
GetDashboardStats
rpc GetDashboardStats(GetDashboardStatsRequest) returns (GetDashboardStatsResponse);- Kind: Unary.
- Auth: Bearer session.
- Errors: None beyond authentication.
Computes a few live counters and leaves every other field unset. Treat an unset field as “not reported”, not as zero:
dashboard_stats.total_active_agentscounts the runners thatConfigService.ListRunnersreports as running.twins_dashboard.action_queue_depthcounts the pending action cards, after operator decisions are applied.twins_dashboard.impact_potentialis the total value of the action cards that are undecided or approved, formatted as$<n>.<nn>M. Rejected cards are left out. The field is set only when that total is positive.
financial_metrics, profile_details and inference_outcomes are not set by this RPC.
Financial figures come from an analysis run. See
Analysis, posture & rules.
Request: GetDashboardStatsRequest
No fields.
Response: GetDashboardStatsResponse
| Field | Type | Description |
|---|---|---|
dashboard_stats | DashboardStats | Always present. Only total_active_agents is computed. |
financial_metrics | FinancialMetrics | Not set by this RPC. |
twins_dashboard | TwinsDashboardStats | Always present. Only action_queue_depth and impact_potential are computed. |
profile_details | ProfileDetails | Not set by this RPC. |
inference_outcomes | InferenceOutcomes | Not set by this RPC. |
Messages
ServiceAccount
| Field | Type | Description |
|---|---|---|
id | string | Account id, sa-<name>. |
tenant_id | string | The tenant the account acts in. |
name | string | Account name. |
role | Role | Always ROLE_SERVICE_ACCOUNT. |
Tenant
Defined in commons_defs.proto and used by no RPC on this page.
| Field | Type | Description |
|---|---|---|
id | string | Tenant id. |
name | string | Display name. |
subscription | SubscriptionTier | Subscription tier. |
seats | int32 | Seat count. |
base_cu_allowance | int32 | Base compute-unit allowance. |
DashboardStats
| Field | Type | Description |
|---|---|---|
system_health | string | Not set by GetDashboardStats. |
tasks_completed_today | int32 | Not populated. Always 0. Treat it as absent, not as “nothing completed”. |
total_active_agents | int32 | Runners reported as running. 0 means no running runner was observed. |
uptime_hours | double | Not set by GetDashboardStats. |
error_rate | string | Not set by GetDashboardStats. |
latency_p95 | string | Not set by GetDashboardStats. |
FinancialMetrics
| Field | Type | Description |
|---|---|---|
revenue | string | Revenue figure. |
revenue_trend | string | Revenue trend. |
margin | string | Margin label. |
margin_value | string | Margin value. |
capex | string | Capital expenditure. |
capex_trend | string | Capex trend. |
opex | string | Operating expenditure. |
opex_trend | string | Opex trend. |
TwinsDashboardStats
| Field | Type | Description |
|---|---|---|
high_priority_match | string | Not set by GetDashboardStats. |
high_priority_recovery | string | Not set by GetDashboardStats. |
impact_potential | string | Total value of undecided and approved action cards, $<n>.<nn>M. Unset when the total is zero. |
impact_trend | string | Not set by GetDashboardStats. |
normal_priority_eta | string | Not set by GetDashboardStats. |
normal_priority_premium | string | Not set by GetDashboardStats. |
action_queue_depth | int32 | Pending action cards, after operator decisions. |
pipeline_throughput | string | Not set by GetDashboardStats. |
ProfileDetails
| Field | Type | Description |
|---|---|---|
license_type | string | Licence type label. |
remaining_days | string | Days left on the licence. |
InferenceOutcomes
| Field | Type | Description |
|---|---|---|
confidence_score | double | Confidence score. |
stochastic_candles | repeated double | Series values. |
model_version | string | Model version label. |
Enums
LoginRequest.AuthMethod
| Value | Meaning |
|---|---|
AUTH_METHOD_UNSPECIFIED | Not set. Login fails with Unsupported authentication method. |
AUTH_METHOD_GOOGLE_OIDC | Sign in with an OIDC ID token from the deployment’s configured issuer. |
AUTH_METHOD_CREDENTIALS | Username (email) and password. |
AUTH_METHOD_MFA_VERIFY | Second step: TOTP challenge response. |
Reserved: value 1 (AUTH_METHOD_LICENSE_KEY).
LoginResponse.Status
| Value | Meaning |
|---|---|
STATUS_UNSPECIFIED | Not set. |
STATUS_SUCCESS | Signed in. token is set. |
STATUS_FAILURE | Not signed in. message says why. |
STATUS_MFA_REQUIRED | Password accepted. Send the TOTP code with mfa_session. |
Role
| Value | Meaning |
|---|---|
ROLE_UNSPECIFIED | No role. A session whose role is not recognised is refused. |
ROLE_ORG_ADMIN | Administrator. |
ROLE_WRITER | Editor. |
ROLE_READER | Viewer. |
ROLE_SERVICE_ACCOUNT | Machine credential from GenerateServiceAccountKey. |
SubscriptionTier
| Value | Meaning |
|---|---|
SUBSCRIPTION_TIER_UNSPECIFIED | Not set. |
SUBSCRIPTION_TIER_TRIAL | Trial. Cloud-only features, such as creating a Databricks cluster, are refused. |
SUBSCRIPTION_TIER_CLOUD | Cloud: runners in the customer’s own cloud account. |
SUBSCRIPTION_TIER_ON_PREMISES | On-premises: the customer’s own servers, or their cloud by arrangement. |