Register device

Request bodyDeviceRegistration

• platformstringRequired
  APNS for an iOS device, FCM for an Android device
  • APNS
  • FCM
• tokenstringRequired
  The APNs device token (hex) or the FCM registration token, exactly as the OS handed it to the app.Show more

  The APNs device token (hex) or the FCM registration token, exactly as the OS handed it to the app. Treated like a credential: stored for sending, never logged, never returned (a response shows tokenSuffix only).
• appVersionstringOptional
  The app's version string, for support only; refreshed on every registration

Responses

• 200This user had already registered the token — the same device, appVersion refreshedDevice
• 201Registered for the caller — a new token, or one moved from another userDevice
• 400VALIDATION — platform is not APNS or FCM, or the token is empty or longer than 4096 charactersApiErrorResponse
• 401
  UNAUTHENTICATED — missing or expired token.Show more

  UNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
  ApiErrorResponse
• 403
  The 403 of the /v1/devices routes: PERMISSION_DENIED with details.reason SESSION_REQUIRED when the credential is not a human session — an API key (X-Api-Key) or a service token from POST…Show more

  The 403 of the /v1/devices routes: PERMISSION_DENIED with details.reason SESSION_REQUIRED when the credential is not a human session — an API key (X-Api-Key) or a service token from POST /v1/oauth/token, whatever its scopes. A device belongs to a person, and only a person's session can register, list or delete one.
  ApiErrorResponse
• 405
  VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show more

  VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
  ApiErrorResponse
• 413
  VALIDATION — the request body is larger than the surface's limit.Show more

  VALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
  ApiErrorResponse
• 414
  VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show more

  VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
  ApiErrorResponse
• 415
  VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show more

  VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
  ApiErrorResponse
• 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.