Skip to content
Identity, licences & landing

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

ServiceRPCKindPurpose
IdentityServiceLoginUnaryExchange credentials, a TOTP code or an OIDC ID token for a session token
IdentityServiceLogoutUnaryEnd every session of the calling account
IdentityServiceDeleteAccountUnaryDelete the caller’s own account, after a typed confirmation
IdentityServiceEnrollTotpUnaryGenerate a TOTP secret to enrol
IdentityServiceConfirmTotpUnaryProve the authenticator works and turn two-factor on
IdentityServiceUpdateUserUnaryChange an account’s email, role or password
IdentityServiceCreateInstanceUnaryAcknowledge an instance request (provisions nothing)
IdentityServiceGenerateServiceAccountKeyUnaryMint a service-account token for the caller’s tenant
ActivationServiceValidateLicenseUnaryCheck a signed licence key
LandingServiceGetDashboardStatsUnaryLive 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: INTERNAL if 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 with status: STATUS_FAILURE and a human-readable message.

Login is a one-step or two-step exchange, selected by method:

methodRequired fieldsOutcome
AUTH_METHOD_CREDENTIALSusername (the account email), password; captcha_token when the deployment enforces reCAPTCHASTATUS_SUCCESS with token, or STATUS_MFA_REQUIRED with mfa_session if the account has TOTP enabled
AUTH_METHOD_MFA_VERIFYmfa_session (from the previous response), mfa_code (6-digit TOTP)STATUS_SUCCESS with token
AUTH_METHOD_GOOGLE_OIDCoidc_token (an OIDC ID token from the deployment’s configured issuer); captcha_token when the deployment enforces reCAPTCHASTATUS_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_session from a STATUS_MFA_REQUIRED response 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 Login are 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

FieldTypeDescription
methodLoginRequest.AuthMethodWhich sign-in step this is.
usernamestringAccount email, for AUTH_METHOD_CREDENTIALS.
passwordstringAccount password, for AUTH_METHOD_CREDENTIALS.
captcha_tokenstringreCAPTCHA 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_tokenstringOIDC ID token, for AUTH_METHOD_GOOGLE_OIDC.
mfa_codestring6-digit TOTP code, for AUTH_METHOD_MFA_VERIFY.
mfa_sessionstringThe mfa_session returned by the credentials step, for AUTH_METHOD_MFA_VERIFY.

Reserved: field 2 (key).

Response: LoginResponse

FieldTypeDescription
statusLoginResponse.StatusOutcome of this step.
tokenstringThe session token (a signed JWT) on STATUS_SUCCESS. Send it as authorization: Bearer <token>.
messagestringHuman-readable outcome, safe to show to the user.
mfa_sessionstringShort-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: UNAUTHENTICATED if the session carries no subject. INTERNAL if 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

FieldTypeDescription
tokenstringIgnored. The session revoked is the one authenticating the call.

Response: LogoutResponse

FieldTypeDescription
successbooltrue once the sessions are revoked.

DeleteAccount

rpc DeleteAccount(DeleteAccountRequest) returns (DeleteAccountResponse);
  • Kind: Unary.
  • Auth: Bearer session, any role. Service-account tokens are refused.
  • Errors: UNAUTHENTICATED with no verified session. PERMISSION_DENIED for a service account. INVALID_ARGUMENT when confirm_email is not the caller’s own address. FAILED_PRECONDITION when the caller is the last organisation admin, or the deployment’s break-glass admin, or the session carries no email. UNAVAILABLE when the accounts could not be read. INTERNAL when 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

FieldTypeDescription
confirm_emailstringThe caller’s own email address, typed by the person.

Response: DeleteAccountResponse

FieldTypeDescription
deletedbooltrue once the account no longer exists and its sessions are ended.
already_deletedbooltrue when the account was already gone (a repeat after success).
deleted_classesrepeated stringThe classes of data deleted.
retained_classesrepeated stringThe classes the organisation retains.
pseudonymstringThe code that stands for the person in retained records.
storage_statusstringscheduled while earlier encrypted versions may remain in storage history; complete only after the erase service’s read-back listed nothing.
storage_scheduled_untilstringRFC 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_DENIED if 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. INTERNAL if 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

FieldTypeDescription
emailstringEmail of the account to enrol.

Response: EnrollTotpResponse

FieldTypeDescription
successboolWhether a secret was generated.
secretstringBase32 shared secret. Keep it for ConfirmTotp.
provisioning_uristringotpauth:// URI, usually rendered as a QR code.
messagestringHuman-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_DENIED under the same conditions as EnrollTotp. INTERNAL if 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

FieldTypeDescription
emailstringEmail of the account being enrolled.
secretstringThe secret returned by EnrollTotp.
codestringCurrent 6-digit code from the authenticator app.

Response: ConfirmTotpResponse

FieldTypeDescription
successbooltrue once two-factor is enabled.
messagestringHuman-readable outcome.

UpdateUser

rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);
  • Kind: Unary.
  • Auth: Bearer session, org admin only. Service-account tokens are refused.
  • Errors: PERMISSION_DENIED for any role other than org admin. INTERNAL if 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

FieldTypeDescription
user_idstringRequired. The account to change.
emailstringNew email. Empty leaves it unchanged.
rolestringNew role. Empty leaves it unchanged.
passwordstringNew password. Empty leaves it unchanged.
is_activeboolNot 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

FieldTypeDescription
successboolWhether the change was applied.
messagestringHuman-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

FieldTypeDescription
idstringRequested instance id, for example org-example-prod.
namestringDisplay name, for example Production Environment.

Reserved: field 1 (license_key).

Response: CreateInstanceResponse

FieldTypeDescription
successboolAlways true.
instance_idstringThe id from the request.
messagestringHuman-readable outcome.

GenerateServiceAccountKey

rpc GenerateServiceAccountKey(GenerateServiceAccountKeyRequest) returns (GenerateServiceAccountKeyResponse);
  • Kind: Unary.
  • Auth: Bearer session, org admin only. Service-account tokens are refused.
  • Errors: INVALID_ARGUMENT if name is empty or is a name reserved for an internal credential. PERMISSION_DENIED if the caller is not an org admin, if the session has no verified tenant, or if tenant_id names a tenant other than the caller’s. INTERNAL if 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

FieldTypeDescription
tenant_idstringOptional. If set, it must equal the caller’s own tenant. The server never issues a key for another tenant.
namestringRequired. Service-account name. The account id becomes sa-<name>.

Response: GenerateServiceAccountKeyResponse

FieldTypeDescription
api_keystringThe bearer token. Shown once.
accountServiceAccountThe 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

FieldTypeDescription
license_keystringThe signed licence, as JSON or base64-encoded JSON.

Response: ValidateLicenseResponse

FieldTypeDescription
validboolSignature verified and within the validity window.
customer_emailstringNot populated by the server.
expires_atstringNot populated by the server.
remaining_daysint32Not populated by the server.
subscriptionstringNot 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_agents counts the runners that ConfigService.ListRunners reports as running.
  • twins_dashboard.action_queue_depth counts the pending action cards, after operator decisions are applied.
  • twins_dashboard.impact_potential is 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

FieldTypeDescription
dashboard_statsDashboardStatsAlways present. Only total_active_agents is computed.
financial_metricsFinancialMetricsNot set by this RPC.
twins_dashboardTwinsDashboardStatsAlways present. Only action_queue_depth and impact_potential are computed.
profile_detailsProfileDetailsNot set by this RPC.
inference_outcomesInferenceOutcomesNot set by this RPC.

Messages

ServiceAccount

FieldTypeDescription
idstringAccount id, sa-<name>.
tenant_idstringThe tenant the account acts in.
namestringAccount name.
roleRoleAlways ROLE_SERVICE_ACCOUNT.

Tenant

Defined in commons_defs.proto and used by no RPC on this page.

FieldTypeDescription
idstringTenant id.
namestringDisplay name.
subscriptionSubscriptionTierSubscription tier.
seatsint32Seat count.
base_cu_allowanceint32Base compute-unit allowance.

DashboardStats

FieldTypeDescription
system_healthstringNot set by GetDashboardStats.
tasks_completed_todayint32Not populated. Always 0. Treat it as absent, not as “nothing completed”.
total_active_agentsint32Runners reported as running. 0 means no running runner was observed.
uptime_hoursdoubleNot set by GetDashboardStats.
error_ratestringNot set by GetDashboardStats.
latency_p95stringNot set by GetDashboardStats.

FinancialMetrics

FieldTypeDescription
revenuestringRevenue figure.
revenue_trendstringRevenue trend.
marginstringMargin label.
margin_valuestringMargin value.
capexstringCapital expenditure.
capex_trendstringCapex trend.
opexstringOperating expenditure.
opex_trendstringOpex trend.

TwinsDashboardStats

FieldTypeDescription
high_priority_matchstringNot set by GetDashboardStats.
high_priority_recoverystringNot set by GetDashboardStats.
impact_potentialstringTotal value of undecided and approved action cards, $<n>.<nn>M. Unset when the total is zero.
impact_trendstringNot set by GetDashboardStats.
normal_priority_etastringNot set by GetDashboardStats.
normal_priority_premiumstringNot set by GetDashboardStats.
action_queue_depthint32Pending action cards, after operator decisions.
pipeline_throughputstringNot set by GetDashboardStats.

ProfileDetails

FieldTypeDescription
license_typestringLicence type label.
remaining_daysstringDays left on the licence.

InferenceOutcomes

FieldTypeDescription
confidence_scoredoubleConfidence score.
stochastic_candlesrepeated doubleSeries values.
model_versionstringModel version label.

Enums

LoginRequest.AuthMethod

ValueMeaning
AUTH_METHOD_UNSPECIFIEDNot set. Login fails with Unsupported authentication method.
AUTH_METHOD_GOOGLE_OIDCSign in with an OIDC ID token from the deployment’s configured issuer.
AUTH_METHOD_CREDENTIALSUsername (email) and password.
AUTH_METHOD_MFA_VERIFYSecond step: TOTP challenge response.

Reserved: value 1 (AUTH_METHOD_LICENSE_KEY).

LoginResponse.Status

ValueMeaning
STATUS_UNSPECIFIEDNot set.
STATUS_SUCCESSSigned in. token is set.
STATUS_FAILURENot signed in. message says why.
STATUS_MFA_REQUIREDPassword accepted. Send the TOTP code with mfa_session.

Role

ValueMeaning
ROLE_UNSPECIFIEDNo role. A session whose role is not recognised is refused.
ROLE_ORG_ADMINAdministrator.
ROLE_WRITEREditor.
ROLE_READERViewer.
ROLE_SERVICE_ACCOUNTMachine credential from GenerateServiceAccountKey.

SubscriptionTier

ValueMeaning
SUBSCRIPTION_TIER_UNSPECIFIEDNot set.
SUBSCRIPTION_TIER_TRIALTrial. Cloud-only features, such as creating a Databricks cluster, are refused.
SUBSCRIPTION_TIER_CLOUDCloud: runners in the customer’s own cloud account.
SUBSCRIPTION_TIER_ON_PREMISESOn-premises: the customer’s own servers, or their cloud by arrangement.