Notify API reference

Notify API · Channels

put/v1/workspaces/{workspace_id}/channels/fcm/credentialsAuth

Upload an FCM service account

Uploads the JSON key of a Google service account for one Firebase project (FCM HTTP v1). You still create the service account and its key in your Google Cloud project; Notify validates it with Google before activating it (an OAuth token request and a `validate_only` message to a placeholder token that reaches no device), stores the private key encrypted and never returns it. Use a dedicated service account with only the "Firebase Cloud Messaging API Admin" role: the Firebase Admin SDK account (`firebase-adminsdk-*`) is accepted with a `warnings` entry because it can do far more than send push. An upload replaces the active or invalid credential of the same project (`replaced_credential_ids`) and resumes push for that project if Google had refused the previous one. Uploading the active account again unchanged only re-validates it. Nothing is stored when Google refuses the account or cannot be reached.

Path parameters

workspace_id*string · uuid

Id of the workspace.

Headers

Idempotency-Keystring

A key (1..256 chars, [A-Za-z0-9._:-]) makes retries safe: a replay returns the original response for 24 h.

Request body

service_account*string

The full text of the service-account JSON key file (Google Cloud console > IAM & Admin > Service Accounts > Keys > Add key > JSON). Use a dedicated service account with only the "Firebase Cloud Messaging API Admin" role. Write-only: validated with Google, the private key is stored encrypted and never returned; responses show the project id, the account email and a fingerprint.

Response · 200 The active credential for the project (metadata only).

credential_id*string · uuid

The credential id.

project_id*string

The Firebase project id the account sends in. Android devices register with the same value as `app_id`.

Example: "my-app-prod"

client_email*string · email

The service account email.

Example: "notify-push@my-app-prod.iam.gserviceaccount.com"

fingerprint*string

First 16 hex characters of the SHA-256 of the private key; the key itself is never returned.

status*object

`active` after a successful upload; `invalid` once Google refused it while sending.

last_verified_at*string · date-time

When Google last accepted the account (the upload validation).

last_error_code*string

The Google error that made the credential `invalid` (e.g. `THIRD_PARTY_AUTH_ERROR`, `oauth:invalid_grant`).

created_at*string · date-time

When the credential was created.

replaced_credential_ids*array

FCM credentials of the same project that this upload replaced (now `superseded`; their key is erased after 24 h). Empty on a first upload or a no-op re-upload.

warnings*array

Advice about the uploaded account, e.g. when it is the Firebase Admin SDK account (`firebase-adminsdk-*`), which can do far more than send push. The upload is accepted either way.

Example

Request

PUT https://api.notify.productcraft.co/v1/workspaces/{workspace_id}/channels/fcm/credentials
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "service_account": "string"
}

Response

{
  "credential_id": "00000000-0000-0000-0000-000000000000",
  "project_id": "my-app-prod",
  "client_email": "notify-push@my-app-prod.iam.gserviceaccount.com",
  "fingerprint": "string",
  "status": {},
  "last_verified_at": "2026-01-01T00:00:00.000Z",
  "last_error_code": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "replaced_credential_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "warnings": [
    "string"
  ]
}