Push Providers API

Early Access
Identity Engine

Note: This feature is only available as a part of Okta Identity Engine. Contact your Okta account team or ask us on our forum (opens new window) for further information.

The Okta Push Providers API provides a centralized integration platform to fetch and manage push provider configurations. Okta administrators can use these APIs to provide their push provider credentials, for example from APNs and FCM, so that Okta can send push notifications to their own custom app authenticator applications.

The Push Providers API supports the following Authorization Schemes:

SSWS - API tokens
Bearer - OAuth2.0 and OpenID Connect

Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.

Note: You can use the Push Providers API as part of the "Create a custom authenticator" flow. See the Custom authenticator integration guide.

Get started

Explore the Push Providers API: (opens new window)

Push Providers operations

The Push Providers API has the following CRUD operations:

Create Push Provider
List Push Providers
Get Push Provider by ID
Update Push Provider
Delete Push Provider

Create Push Provider

POST /api/v1/push-providers

Creates a Push Provider. Each Push Provider must have a unique name.

Permitted OAuth 2.0 scopes

okta.pushProviders.manage

Request path parameters

None

Request query parameters

None

Request body

A Push Provider object

Response body

Returns the created Push Provider response object

Use example

This request creates a Push Provider object:

API Token Request

curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "providerType": "APNS",
  "name": "Example Push Provider 1",
  "configuration": {
    "keyId": "KEY_ID",
    "teamId": "TEAM_ID",
    "tokenSigningKey": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY\n-----END PRIVATE KEY-----\n",
    "fileName": "fileName.p8"
  }
}' "https://${yourOktaDomain}/api/v1/push-providers"

Bearer token request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${oauth_token}" \
-d '{
  "providerType": "APNS",
  "name": "Example Push Provider 1",
  "configuration": {
    "keyId": "KEY_ID",
    "teamId": "TEAM_ID",
    "tokenSigningKey": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY\n-----END PRIVATE KEY-----\n",
    "fileName": "fileName.p8"
  }
}' "https://${yourOktaDomain}/api/v1/push-providers"

Response

{
  "id": "ppchvbeucdTgqeiGxR0g4",
  "providerType": "APNS",
  "name": "Example Push Provider 1",
  "lastUpdatedDate": "2022-01-00T00:00:00.000Z",
  "configuration": {
    "keyId": "KEY_ID",
    "teamId": "TEAM_ID",
    "fileName": "fileName.p8"
  },
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}}/api/v1/push-providers/{pushProviderId}",
      "hints": {
        "allow": [ "GET", "PUT", "DELETE"]
      }
    }
  }
}

List Push Providers

GET /api/v1/push-providers

Lists all available Push Providers

Permitted OAuth 2.0 scopes

okta.pushProviders.read

Request path parameters

None

Request query parameters

Parameter	Type	Description	Required
`type`	String	Returns a list of Push Providers that match the specific `providerType` in the Push Provider object. Supported values: `APNS` or `FCM`	FALSE

Request body

None

Response body

Array of Push Provider response objects

Use example

This request returns all available Push Provider objects:

API token request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/push-providers"

Bearer token request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${oauth_token}" \
"https://${yourOktaDomain}/api/v1/push-providers"

Response

[
  {
    "id": "ppchvbeucdTgqeiGxR0g4",
    "providerType": "APNS",
    "name": "Example Push Provider 1",
    "lastUpdatedDate": "2022-01-00T00:00:00.000Z",
    "configuration": {
      "keyId": "ABC123DEFG",
      "teamId": "DEF123GHIJ",
      "fileName": "fileName.p8"
    },
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}}/api/v1/push-providers/{pushProviderId}",
        "hints": {
          "allow": [ "GET", "PUT", "DELETE"]
        }
      }
    }
  },
  {
    "id": "ppctekcmngGaqeiBxB0g4",
    "providerType": "FCM",
    "name": "Example Push Provider 2",
    "lastUpdatedDate": "2022-01-00T00:00:00.000Z",
    "configuration": {
      "projectId": "PROJECT_ID",
      "fileName": "fileName.json",
    },
    "_links": {
      "self": {
        "href": "https://{yourOktaDomain}}/api/v1/push-providers/{pushProviderId}",
        "hints": {
          "allow": [ "GET", "PUT", "DELETE"]
        }
      }
    }
  }
]

Get Push Provider by ID

GET /api/v1/push-providers/${pushProviderId}

Fetches a Push Provider by its id. If you don't know the id, you can List Push Providers.

Permitted OAuth 2.0 scopes

okta.pushProviders.read

Request path parameters

Parameter	Type	Description
`pushProviderId`	String	The `id` of a Push Provider response object

Request query parameters

None

Request body

None

Response body

The requested Push Provider response object

Use example

This request returns a Push Provider object with an id value ppchvbeucdTgqeiGxR0g4:

API token request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/push-providers/${pushProviderId}"

Bearer token request

curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${oauth_token}" \
"https://${yourOktaDomain}/api/v1/push-providers/${pushProviderId}"

Response

{
  "id": "ppchvbeucdTgqeiGxR0g4",
  "providerType": "APNS",
  "name": "Example Push Provider 1",
  "lastUpdatedDate": "2022-01-00T00:00:00.000Z",
  "configuration": {
    "keyId": "KEY_ID",
    "teamId": "TEAM_ID",
    "fileName": "fileName.p8"
  },
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}}/api/v1/push-providers/{pushProviderId}",
      "hints": {
        "allow": [ "GET", "PUT", "DELETE"]
      }
    }
  }
}

Error response

Passing an invalid id returns a 404 Not Found status code with error code E0000007.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "errorCode": "E0000007",
  "errorSummary": "Not found: Resource not found: 123456 (PushProviderConfigEntity)",
  "errorLink": "E0000007",
  "errorId": "oaeksGocbBmG9OGYo4vXF7llA",
  "errorCauses": []
}

Update Push Provider

PUT /api/v1/push-providers/${pushProviderId}

Updates a Push Provider

Permitted OAuth 2.0 scopes

okta.pushProviders.manage

Request path parameters

Parameter	Type	Description
`pushProviderId`	String	The `id` of a Push Provider response object

Request body

A Push Provider object

Response body

Returns the updated Push Provider response object

Use example

This request updates a Push Provider object:

API token request

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
  "providerType": "APNS",
  "name": "Updated Example Push Provider 1",
  "configuration": {
    "keyId": "KEY_ID",
    "teamId": "TEAM_ID",
    "tokenSigningKey": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY\n-----END PRIVATE KEY-----\n",
    "fileName": "fileName.p8"
  }
}' "https://${yourOktaDomain}/api/v1/push-providers/${pushProviderId}"

Bearer token request

curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${oauth_token}" \
-d '{
  "providerType": "APNS",
  "name": "Updated Example Push Provider 1",
  "configuration": {
    "keyId": "KEY_ID",
    "teamId": "TEAM_ID",
    "tokenSigningKey": "-----BEGIN PRIVATE KEY-----\nPRIVATE_KEY\n-----END PRIVATE KEY-----\n",
    "fileName": "fileName.p8"
  }
}' "https://${yourOktaDomain}/api/v1/push-providers/${pushProviderId}"

Response

{
  "id": "ppchvbeucdTgqeiGxR0g4",
  "providerType": "APNS",
  "name": "Updated Example Push Provider 1",
  "lastUpdatedDate": "2022-02-00T00:00:00.000Z",
  "configuration": {
    "keyId": "KEY_ID",
    "teamId": "TEAM_ID",
    "fileName": "fileName.p8"
  },
  "_links": {
    "self": {
      "href": "https://{yourOktaDomain}}/api/v1/push-providers/{pushProviderId}",
      "hints": {
        "allow": [ "GET", "PUT", "DELETE"]
      }
    }
  }
}

Delete Push Provider

DELETE /api/v1/push-providers/${pushProviderId}

Deletes a Push Provider

Permitted OAuth 2.0 scopes

okta.pushProviders.manage

Request path parameters

Parameter	Type	Description
`pushProviderId`	String	The `id` of Push Provider response object

Request body

None

Response body

None

Use example

This request permanently deletes a Push Provider object:

API token request

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/push-providers/${pushProviderId}"

Bearer token request

curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${oauth_token}" \
"https://${yourOktaDomain}/api/v1/push-providers/${pushProviderId}"

Response

HTTP/1.1 204 No Content
Content-Type: application/json

Error responses

Passing an invalid id returns a 404 Not Found status code with error code E0000007.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "errorCode": "E0000007",
  "errorSummary": "Not found: Resource not found: 123456 (PushProviderConfigEntity)",
  "errorLink": "E0000007",
  "errorId": "oaeksGocbBmG9OGYo4vXF7llA",
  "errorCauses": []
}

Passing an id that is configured in a custom app authenticator returns a 409 Conflict status code with the error code E0000187. The error occurs as long as the custom app authenticator is ACTIVE or DEACTIVATED.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "errorCode": "E0000187",
  "errorSummary": "Cannot delete push provider because it is being used by a custom app authenticator.",
  "errorLink": "E0000187",
  "errorId": "oaenwA1ra80S9W-pvbh4m6haA",
  "errorCauses": [
    {
      "errorSummary": "Cannot delete push provider notification service configuration with id={{pushProviderId}} because it is associated with the following custom app authenticator ids=[{{authenticatorId}}]. Please unassociate it from the authenticators and try again."
    }
  ]
}