> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rivi.software/llms.txt
> Use this file to discover all available pages before exploring further.
# Integrations
> Connect listener services and external automation with station credentials.
Create a separate credential for each trusted integration. Credentials identify a service, belong to one station, and carry explicit scopes.
## Create a credential
1. Check the active station and open **Settings → Credentials**.
2. Choose the **Credential type**: **Machine** for automation, or **Integration** with **Observed playback** for track reporting.
3. Enter a descriptive **Label**, choose a **Validity period**, and select the required **Scopes**.
4. Choose **Create credential**. Choose **Reveal token**, then **Copy token**, and store the secret in the consumer's secret storage. Choose **I have stored it** when you finish.
5. Test the intended operation and check the credential's last-used time before relying on it.
Secrets are shown once and cannot be retrieved later. Choose a validity period of 30, 90, 180, or 365 days. Use **No expiry** only for long-running integrations: the token stays valid until you revoke it. You need **Manage API credentials** and cannot grant scopes for actions you are not allowed to perform yourself.
| Consumer | Scope and purpose |
| - | - |
| Listener website or app server | **Read listener data** (`listener:read`) for published JSON, GraphQL, and the public socket |
| Listener app registration service | **Register push devices** (`push:register`) for device registration and topic changes |
| External automation or encoder | An **Observed playback** integration with **Send now-playing** (`ingest:write`) |
| Editorial or scheduling automation | Content, publishing, schedule, or live scopes, only as needed |
Keep listener credentials on your consumer server. Browser and mobile clients call your service, which forwards authenticated requests to RadioTools. Do not put tokens in URLs or shipped app bundles.
## Send reported tracks
Configure an **Observed playback** integration to send metadata to:
```http theme={null}
POST /api/v1/integrations/playback?stationId=
Authorization: Bearer
Content-Type: application/json
```
A stream-title payload can look like this fictional RIVI FM example:
```json theme={null}
{ "streamTitle": "The Riverside Sessions - Morning Light" }
```
Or send separate artist and title fields. Include stable event IDs and timestamps when supported.
Open **Settings → Playback and encoder** to verify the result. It shows the latest reported track, the **Track reporting status** with the last event and its outcome, when the credential was last used, any observations rejected in the last 24 hours, and **Recent tracks**. This page is available while the **Playback** module is on.
Now-playing and history can receive metadata independently of a live rundown. **Follow automation** only advances a matching live broadcast within its eligible window and when the station and presenter enable it. Receiving a track does not start audio playout.
See [Now-playing ingest](/radiotools/api-reference/now-playing-ingest) for the complete operation and [Live presentation](/radiotools/daily-work/live-presentation) for following behavior.
## Rotate or revoke
Before rotating, identify every consumer that uses the credential. **Rotate** creates a new secret with the same access and revokes the old credential. The new token keeps the old one's remaining validity. Update the consumer with the replacement secret and confirm successful requests.
Use **Revoke** when access must end. The credential stops working immediately and cannot be restored. Never include secrets in screenshots or support messages.
## Provider integrations
Some studio features use the station's own provider accounts. Their credentials are encrypted, never shown after saving, and never included in station exports.
| Page | What it connects |
| - | - |
| **Settings → Artwork** | Cover art lookup for reported tracks with the station's own Spotify, Apple Music, or Last.fm credentials. Lookup stays off until you turn it on. |
| **Settings → Listener alerts** | The **Push provider** for your listener apps: Firebase Cloud Messaging, Apple Push Notification service, or Expo. |
On **Listener alerts**, use **Send a test alert to my device** with the push token your listener app shows. The alert goes to that device only. Use **Turn off and clear credential** to stop sending.
Each integration page shows a status line, such as **Fresh**, **Stale**, **Waiting**, **Not configured**, or **Module off**. Station AI does not need a provider credential; see [AI settings](/radiotools/station-admin/ai-settings).
When billing is enabled, creating or rotating credentials and saving a push provider require an active subscription. Restore the subscription before issuing new ones. Listener API switches and redistribution permission remain separate from credential scope.
## Related topics
- [Authentication](/radiotools/api-reference/authentication.md)
- [API overview](/radiotools/api-reference/overview.md)
- [SDKs](/radiotools/api-reference/sdks/index.md)
- [Onboarding checklist](/radiotools/station-admin/onboarding.md)
- [Station administration](/radiotools/station-admin/index.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.