auth.v1.SocialVerificationService

StartSocialVerification

Start or restart social verification by issuing a new challenge code.

Method

POST

Path

auth.v1.SocialVerificationService/StartSocialVerification

Service

auth.v1.SocialVerificationService

Visibility

Authentication required

Authentication

Session token

MFA Requirement

Not required

POST

auth.v1.SocialVerificationService/StartSocialVerification

Request

Testnet

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

Responses

{
  "challengeCode": "POLY-VERIFY-7K2M",
  "expiresAt": "2025-01-01T00:00:00Z",
  "verification": {
    "attempts": 1,
    "challengeCode": "POLY-VERIFY-7K2M",
    "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.StartSocialVerificationRequest

Response

auth.v1.StartSocialVerificationResponse

provider enum must be defined value

Provider account to verify.

method enum must be defined value

Verification method. If unspecified, profile verification is used for X/Twitter and channel verification is used for Discord.

handle string max 64 chars handle must not contain '<' or '>'

Provider handle the user claims. Required for X/Twitter and omitted for Discord, where the authenticated bot supplies the provider identity. A leading "@" is accepted and removed from X/Twitter handles.

challengeCode string

Newly issued challenge code the user must submit according to the verification method.

expiresAt string (date-time)

Time in UTC when the challenge code expires. Social verification challenges expire after 15 minutes.

14 fields

id string (int64)

Verification identifier.

provider enum

Provider account being verified.

TWITTER DISCORD

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 "@".

providerUserId string

Stable provider-side user identifier. Empty until verification succeeds.

challengeCode string

Challenge code the user must submit according to the verification method. Discord 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

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

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/StartSocialVerification

Request

Testnet

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

Responses

{
  "challengeCode": "POLY-VERIFY-7K2M",
  "expiresAt": "2025-01-01T00:00:00Z",
  "verification": {
    "attempts": 1,
    "challengeCode": "POLY-VERIFY-7K2M",
    "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"
  }
}