Skip to contentSkip to navigationSkip to topbar
Twilio Docs
Page tools
On this page
Looking for more inspiration?Visit the

Credentials resource

(new)

Beta

The Push Notifications API is currently available as a Private Beta product. The information contained in this document is subject to change. You acknowledge and agree that your use of the Twilio Push Notifications API is subject to the terms of the Services in Private Beta(link takes you to an external page). This means that some features are not yet implemented and others may be changed before the product is declared as Generally Available. Private Beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.

A Credential resource represents the authentication credentials required to send push notifications through a specific platform. Twilio supports two credential types:

  • FCM: Google Firebase Cloud Messaging credentials for Android devices and all web browsers (including Safari).
  • APN: Apple Push Notification service credentials for iOS devices.

After you upload a Credential, it is associated with an App. If you don't specify an App, the Credential is associated with your default App.

(information)

Info

You can create a maximum of 10 Apps per account and 10 Credentials per App.

Credential Properties

credential-properties page anchor
Property nameTypeRequiredPIIDescriptionChild properties
idstring
required
Not PII

A reference to Credential.

Example: comms_credential_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_credential_[a-hjkmnpqrstv-z0-9]{26,34}
credentialTypeenum<string>
required
Not PII

The credential types available for PushNotifications.

Possible values:
APNAPN_SANDBOXFCM
isDefaultboolean
required
Not PII

Use this Credential as the default for the Push Notification App for the given credentialType to send Push Notifications. If a Credential of the given type doesn't already exist, this Credential automatically becomes the default.

Default: false
appNamestring
required
Not PII

The name of the app that this Credential is associated with. This should be the same value as the appName set when registering devices for the app with /PushNotifications/DeviceRegistrations

createdAtstring<date-time>
required
Not PII
updatedAtstring<date-time>
required
Not PII

Credential types

credential-types page anchor
credentialTypeDescription
FCMFirebase Cloud Messaging. Requires a base64-encoded privateKey (Google Cloud private key JSON object) in content.
APNApple Push Notification service. Requires a base64-encoded certificate and privateKey in content.

Create a Credential

create-a-credential page anchor

POST https://comms.twilio.com/v1/PushNotifications/Credentials

Upload new push notification credentials by making an HTTP POST request to the Credentials resource URI.

When creating a Credential, specify an appName. If the App doesn't exist, the API creates it. If no other Apps exist, the API sets the created App as the default.

(information)

Info

The certificate and privateKey values in the content object must be base64-encoded. See Obtain FCM credentials or Obtain APNs credentials for encoding instructions.

Request body parameters

request-body-parameters page anchor
Encoding type:application/json
SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
credentialTypeenum<string>
required
Not PII

The credential types available for PushNotifications.

Possible values:
APNAPN_SANDBOXFCM
content
oneOf:
required
Not PII

Credential properties are specific to the channel type and provided by the vendor that supports it.

isDefaultboolean

Optional

Not PII

Use this Credential as the default for the Push Notification App for the given credentialType to send Push Notifications. If a Credential of the given type doesn't already exist, this Credential automatically becomes the default.

Default: false
appNamestring
required
Not PII

The name of the App that this Credential will be associated with.

Twilio will automatically create a new Push Notification App on your behalf when you create a Credential with a new appName.

The first App created will automatically be assigned as the default App.

Pattern: ^[a-z0-9_]+$Min length: 1Max length: 64

Responses

responses page anchor
202400429500503

The request was accepted and a resource ID is available to check the result. The response body contains the resource ID and link to the resource.

SchemaExample
Property nameTypeRequiredDescriptionChild properties
resourceIdstring

Optional

The Resource ID is an identifier for the resource that was created or updated in response to the request.

resourceLocationstring<uri>

Optional

The location (uri) of the resource identified by Resource-Id.

Create a Push CredentialLink to code sample: Create a Push Credential
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "<username>",

6
        authToken: "<password>",

7
    });

8
    await client.pushNotifications.credentials.create({

9
        credentialType: "APN",

10
        content: {

11
            certificate: "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tTUlJRm5UQ0NCSVdnQXdJQkFnSUlBank5SDg0OStFOHdEUVlKS29aSWh2Y05BUUVGQlFBd2daWXhDekFKQmdOVi4uLi4uQT09LS0tLS1FTkQgQ0VSVElGSUNBVEUtLS0tLQ==",

12
            privateKey: "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLU1JSUVwUUlCQUFLQ0FRRUF1eWYvbE5ySDljazhEbU55bzNmR2d2Q0kxbDlzK2NtQlkzV0l6K2NVRHFteGlpZVIKLi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0t",

13
        },

14
        appName: "limonade_app",

15
    });

16
}

17
main();

Fetch a Credential

fetch-a-credential page anchor

GET https://comms.twilio.com/v1/PushNotifications/Credentials/{credentialId}

Retrieve a single Credential resource by making an HTTP GET request to the Credential resource URI with the Credential ID.

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
credentialIdstring
required
Not PII
Example: comms_credential_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_credential_[a-hjkmnpqrstv-z0-9]{26,34}

Responses

responses-1 page anchor
200400404429500503

OK

SchemaExample
Property nameTypeRequiredDescriptionChild properties
idstring

Optional

A reference to Credential.

Example: comms_credential_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_credential_[a-hjkmnpqrstv-z0-9]{26,34}
credentialTypeenum<string>

Optional

The credential types available for PushNotifications.

Possible values:
APNAPN_SANDBOXFCM
isDefaultboolean

Optional

Use this Credential as the default for the Push Notification App for the given credentialType to send Push Notifications. If a Credential of the given type doesn't already exist, this Credential automatically becomes the default.

Default: false
appNamestring

Optional

The name of the app that this Credential is associated with. This should be the same value as the appName set when registering devices for the app with /PushNotifications/DeviceRegistrations

createdAtstring<date-time>

Optional

updatedAtstring<date-time>

Optional

Fetch a Push CredentialLink to code sample: Fetch a Push Credential
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "<username>",

6
        authToken: "<password>",

7
    });

8
    await client.pushNotifications.credentials.fetch("comms_credential_01h9krwprkeee8fzqspvwy6nq8");

9
}

10
main();

List Credentials

list-credentials page anchor

GET https://comms.twilio.com/v1/PushNotifications/Credentials

Returns a list of all Credentials associated with your account. You can filter by date range, app name, credential type, or default status.

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
startDatestring<date-time>

Optional

Not PII

Filter to Push Credentials created after the specified date and time.

endDatestring<date-time>

Optional

Not PII

Filter to Push Credentials created before the specified date and time.

appNamestring

Optional

Not PII

Filter Push Credentials by App name

Pattern: ^[a-z0-9_]+$Min length: 1Max length: 64
credentialTypeenum<string>

Optional

Not PII

Filter Push Credentials by type.

Possible values:
APNAPN_SANDBOXFCM
isDefaultboolean

Optional

Not PII

Filter only is_default credentials.

pageTokenstring

Optional

Not PII

The token to retrieve the next page of results.

pageSizeinteger

Optional

Not PII

The number of resources to return in a page.

Default: 50Example: 50Minimum: 1Maximum: 1000

Responses

responses-2 page anchor
200400429500503

OK

SchemaExample
Property nameTypeRequiredDescriptionChild properties
credentialsarray[PushNotificationCredential]

Optional

paginationPaginationMetadata

Optional

Metadata for paginated results. This object contains two tokens to navigate through paginated results.

  • Use next to retrieve the 'next' page in the result list.
  • Use self to retrieve the same page of the result list again.
  • Supply the token in the pageToken query param.
List Push CredentialsLink to code sample: List Push Credentials
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "<username>",

6
        authToken: "<password>",

7
    });

8
    await client.pushNotifications.credentials.list({

9
        startDate: new Date("2024-01-15T09:30:00Z"),

10
        endDate: new Date("2024-01-15T09:30:00Z"),

11
        appName: "appName",

12
        credentialType: "APN",

13
        isDefault: true,

14
        pageToken: "pageToken",

15
        pageSize: 50,

16
    });

17
}

18
main();

Update a Credential

update-a-credential page anchor

PATCH https://comms.twilio.com/v1/PushNotifications/Credentials/{credentialId}

Update an existing Credential by making an HTTP PATCH request to the Credential resource URI with the Credential ID.

You can update whether this Credential is the default for its App and credential type.

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
credentialIdstring
required
Not PII
Example: comms_credential_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_credential_[a-hjkmnpqrstv-z0-9]{26,34}

Request body parameters

request-body-parameters-1 page anchor
Encoding type:application/json
SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
isDefaultboolean
required
Not PII

Use this Credential as the default for the Push Notification App for the given credentialType to send Push Notifications. If a Credential of the given type doesn't already exist, this Credential automatically becomes the default.

Default: false

Responses

responses-3 page anchor
202400404429500503

The request was accepted and a resource ID is available to check the result. The response body contains the resource ID and link to the resource.

SchemaExample
Property nameTypeRequiredDescriptionChild properties
resourceIdstring

Optional

The Resource ID is an identifier for the resource that was created or updated in response to the request.

resourceLocationstring<uri>

Optional

The location (uri) of the resource identified by Resource-Id.

Update a Push CredentialLink to code sample: Update a Push Credential
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "<username>",

6
        authToken: "<password>",

7
    });

8
    await client.pushNotifications.credentials.update("comms_credential_01h9krwprkeee8fzqspvwy6nq8", {

9
        isDefault: true,

10
    });

11
}

12
main();

Delete a Credential

delete-a-credential page anchor

DELETE https://comms.twilio.com/v1/PushNotifications/Credentials/{credentialId}

Delete a Credential by making an HTTP DELETE request to the Credential resource URI with the Credential ID.

If successful, returns HTTP 202 (Accepted) with a resource ID to check the result.

(warning)

Warning

If all Credentials belonging to an App are deleted, the App and its Device Registrations are deleted as well.

Path parameters

path-parameters-2 page anchor
Property nameTypeRequiredPIIDescription
credentialIdstring
required
Not PII
Example: comms_credential_01h9krwprkeee8fzqspvwy6nq8Pattern: ^comms_credential_[a-hjkmnpqrstv-z0-9]{26,34}

Responses

responses-4 page anchor
202400404429500503

The request was accepted and a resource ID is available to check the result. The response body contains the resource ID and link to the resource.

SchemaExample
Property nameTypeRequiredDescriptionChild properties
resourceIdstring

Optional

The Resource ID is an identifier for the resource that was created or updated in response to the request.

resourceLocationstring<uri>

Optional

The location (uri) of the resource identified by Resource-Id.

Delete a Push CredentialLink to code sample: Delete a Push Credential
1
import { TwilioClient } from "twilio-comms";

2


3
async function main() {

4
    const client = new TwilioClient({

5
        accountId: "<username>",

6
        authToken: "<password>",

7
    });

8
    await client.pushNotifications.credentials.delete("comms_credential_01h9krwprkeee8fzqspvwy6nq8");

9
}

10
main();