API Authentication

How to authenticate requests from your backend to the NativeSuite API.

App Credentials

Each app has a credential with two values:

Value	Purpose
App Secret	Used to authenticate API calls from your backend (e.g., sending notifications)
Signing Secret	Used to verify that requests to your API came from NativeSuite (request signing)

Finding Your Credentials

1. Navigate to your app in the dashboard
2. Go to Settings → Credentials
3. Copy the App Secret for API authentication

Using the App Secret

Include your app secret in the X-NativeSuite-Key header:

curl -X POST https://api.staging.nativesuite.io/api/apps/{appId}/notifications/send \
  -H "X-NativeSuite-Key: {your-app-secret}" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Rotating Credentials

If your credential is compromised:

1. Go to your app's Settings → Credentials
2. Click Rotate Credential
3. The old credential is immediately invalidated
4. Update your backend with the new credential

WARNING

Rotating a credential invalidates the old one immediately. Make sure to update your backend before or immediately after rotation to avoid downtime.

Error Responses

API errors follow the RFC 9457 problem details format:

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "X-NativeSuite-Key header is required"
}

Common errors:

Status	Title	Meaning
400	Bad Request	Invalid input (malformed ID, missing required field)
401	Unauthorized	Missing or invalid X-NativeSuite-Key header
403	Forbidden	Credential doesn't belong to this app
404	Not Found	App or resource doesn't exist
422	Unprocessable Entity	Valid request but can't be processed (e.g., no live release)
500	Internal Server Error	Something went wrong on our end