auth.v1.SocialVerificationService

ConfirmSocialVerification

Link the Telegram account that submitted the caller's challenge code. A linked Telegram account becomes a channel to the account, so the caller needs enrolled MFA and a fresh, single-use step-up proof in the X-Auth-Step-Up header, obtained by completing an MFA challenge for fresh step-up. The link consumes the proof; a retried confirmation of an existing link needs no new proof. AUTH_RESOURCE_NOT_FOUND means no verification exists; start one first. AUTH_SOCIAL_VERIFICATION_EXPIRED means the challenge window passed; start a new verification. AUTH_SOCIAL_VERIFICATION_INVALID_STATE means no submitted account awaits confirmation, or provider_user_id is not the account that submitted the code. AUTH_SOCIAL_ACCOUNT_ALREADY_LINKED means that Telegram account is linked to another Polyester account; the verification fails. AUTH_MFA_NOT_ENROLLED means enroll MFA first; AUTH_STEP_UP_REQUIRED and AUTH_STEP_UP_PROOF_UNAVAILABLE mean complete a new fresh step-up and retry.

Method

POST

Path

auth.v1.SocialVerificationService/ConfirmSocialVerification

Service

auth.v1.SocialVerificationService

Visibility

Authentication required

Authentication

Session token

MFA Requirement

Fresh step-up required

POST

auth.v1.SocialVerificationService/ConfirmSocialVerification

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/auth.v1.SocialVerificationService/ConfirmSocialVerification' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "provider": "TWITTER",
  "providerUserId": "123456789012345678"
}'

Responses

{
  "verification": {
    "attempts": 1,
    "challengeCode": "POLY-VERIFY-7K2M",
    "displayName": "value",
    "errorCode": "AUTH_USERNAME_INVALID",
    "expiresAt": "2025-01-01T00:00:00Z",
    "handle": "polyester_trader",
    "id": "1",
    "lastError": "The profile could not be verified.",
    "method": "METHOD_PROFILE",
    "provider": "TWITTER",
    "providerUserId": "123456789012345678",
    "requestedAt": "2025-01-01T00:00:00Z",
    "status": "STATUS_PENDING_USER_ACTION",
    "updatedAt": "2025-01-01T00:00:00Z",
    "verifiedAt": "2025-01-01T00:00:00Z"
  }
}

Request

auth.v1.ConfirmSocialVerificationRequest

Response

auth.v1.ConfirmSocialVerificationResponse

provider enum must be defined value

Provider account to confirm. Only TELEGRAM is accepted.

providerUserId string 1-20 chars /^[1-9][0-9]*$/

Provider user ID the user confirms, as provider_user_id of the verification in STATUS_AWAITING_CONFIRMATION. The request fails when it is not the account that submitted the code, so the user links exactly the account they were shown.

15 fields

id string (int64)

Verification identifier. Public ID. ConnectRPC carries it as int64 (a decimal string in JSON).

provider enum

Provider account being verified.

TWITTER DISCORD TELEGRAM

method enum

Method used for this verification. If unspecified at start time, the provider default is used.

METHOD_PROFILE METHOD_CHANNEL METHOD_DM

handle string

Provider handle being verified. Handles are returned lowercase and without a leading "@". For Telegram, the username of the account that submitted the code; empty when that account has no username.

providerUserId string

Stable provider-side user identifier. Empty until verification succeeds, except for Telegram: while the status is STATUS_AWAITING_CONFIRMATION, it is the numeric user ID of the Telegram account that submitted the code, the value ConfirmSocialVerification takes.

displayName string

Provider display name of the account being verified, for showing it to the user. Telegram only: the account's name, set once the code is submitted. Empty for other providers.

challengeCode string

Challenge code the user must submit according to the verification method. Discord and Telegram codes are returned only when a challenge is issued. Codes expire after 15 minutes.

status enum

Current verification status.

STATUS_PENDING_USER_ACTION STATUS_QUEUED STATUS_IN_PROGRESS STATUS_VERIFIED STATUS_FAILED STATUS_EXPIRED STATUS_CANCELLED STATUS_AWAITING_CONFIRMATION

requestedAt string (date-time)

Time in UTC when the current challenge code was issued.

expiresAt string (date-time)

Time in UTC when the current challenge code expires.

verifiedAt string (date-time)

Time in UTC when verification succeeded. Empty until status is STATUS_VERIFIED.

attempts integer (int32)

Number of recorded provider-check attempts for this challenge.

lastError string

Last verification error, if the most recent check failed. Empty when there is no recorded error.

errorCode enum

Stable machine-readable error code for the current failed verification. AUTH_UNSPECIFIED when no typed error applies.

AUTH_USERNAME_INVALID AUTH_USERNAME_TAKEN AUTH_USERNAME_COOLDOWN AUTH_USERNAME_FEATURE_LOCKED AUTH_USERNAME_RESERVED AUTH_INVALID_REQUEST AUTH_AUTHENTICATION_REQUIRED AUTH_SESSION_KIND_NOT_ALLOWED AUTH_WALLET_LOGIN_FAILED AUTH_RESOURCE_NOT_FOUND AUTH_SUBACCOUNT_ACCESS_DENIED AUTH_API_KEY_ACCESS_DENIED AUTH_API_KEY_INVALID_STATUS_TRANSITION AUTH_POLICY_INVALID AUTH_SMART_ACCOUNT_ALREADY_LINKED AUTH_INVITE_ACCESS_DENIED AUTH_INVITE_INVALID_STATE AUTH_MFA_DISABLED AUTH_MFA_NOT_ENROLLED AUTH_MFA_SESSION_INVALID AUTH_MFA_CHALLENGE_NOT_FOUND AUTH_MFA_CHALLENGE_INVALID AUTH_MFA_CHALLENGE_LOCKED AUTH_MFA_OTP_INVALID AUTH_MFA_RECOVERY_INVALID AUTH_MFA_PASSKEY_NOT_AVAILABLE AUTH_MFA_PASSKEY_CREDENTIAL_INVALID AUTH_MFA_PASSKEY_VERIFY_FAILED AUTH_MFA_ENROLLMENT_BINDING_INVALID AUTH_STEP_UP_REQUIRED AUTH_STEP_UP_PROOF_UNAVAILABLE AUTH_STEP_UP_ALREADY_CLAIMED AUTH_POLICY_IN_USE AUTH_POLICY_LOCKED AUTH_POLICY_SCOPE_MISMATCH AUTH_REVISION_CONFLICT AUTH_MFA_ELEVATION_REQUIRED AUTH_MFA_LAST_FACTOR_REQUIRED AUTH_INTERNAL_ERROR AUTH_TERMS_NOT_ACCEPTED AUTH_SOCIAL_VERIFICATION_EXPIRED AUTH_SOCIAL_VERIFICATION_INVALID_STATE AUTH_SUBACCOUNT_CHALLENGE_INVALID AUTH_SOCIAL_ACCOUNT_ALREADY_LINKED AUTH_TEMPORARILY_UNAVAILABLE AUTH_SUBACCOUNT_OWNER_ROLE_LOCKED AUTH_SIGNATURE_INVALID AUTH_TIMESTAMP_SKEW AUTH_MISSING_HEADERS AUTH_KEY_EXPIRED AUTH_KEY_DISABLED AUTH_IP_NOT_ALLOWED AUTH_API_KEY_NOT_ACCEPTED AUTH_WALLET_ALREADY_LINKED AUTH_RECV_WINDOW_INVALID AUTH_REPLAY_CAPACITY_EXHAUSTED AUTH_PATH_BODY_ID_MISMATCH AUTH_ASSISTANT_KEY_ACTION_NOT_ALLOWED AUTH_ASSISTANT_KEY_PROOF_INVALID AUTH_ASSISTANT_KEY_REGISTRATION_EXPIRED AUTH_ASSISTANT_KEY_DEADLINE_TOO_FAR AUTH_REPLAY_DETECTED

updatedAt string (date-time)

Time in UTC when this verification state last changed.

Possible errors: 5

Key	HTTP status	Connect code	Error	When
unauthenticated	401	unauthenticated	Unauthenticated	Authentication required.
permission-denied	403	permission_denied	Permission Denied	Permission denied.
invalid-argument	400	invalid_argument	Invalid Argument	Invalid argument.
not-found	404	not_found	Not Found	Not found.
unavailable	503	unavailable	Unavailable	Service unavailable.

POST

auth.v1.SocialVerificationService/ConfirmSocialVerification

Request

Testnet

curl --request POST \ \
  --url 'https://api.testnet.polyester.com/auth.v1.SocialVerificationService/ConfirmSocialVerification' \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{
  "provider": "TWITTER",
  "providerUserId": "123456789012345678"
}'

Responses

{
  "verification": {
    "attempts": 1,
    "challengeCode": "POLY-VERIFY-7K2M",
    "displayName": "value",
    "errorCode": "AUTH_USERNAME_INVALID",
    "expiresAt": "2025-01-01T00:00:00Z",
    "handle": "polyester_trader",
    "id": "1",
    "lastError": "The profile could not be verified.",
    "method": "METHOD_PROFILE",
    "provider": "TWITTER",
    "providerUserId": "123456789012345678",
    "requestedAt": "2025-01-01T00:00:00Z",
    "status": "STATUS_PENDING_USER_ACTION",
    "updatedAt": "2025-01-01T00:00:00Z",
    "verifiedAt": "2025-01-01T00:00:00Z"
  }
}