Acting for Users
Catalog endpoints accept X-User-Id so a trusted organization integration can perform an allowed artist, release, track, or split action for a user in the same organization.
On catalog writes and uploads the header is mandatory, not optional. Send it and the request is attributed to that user; omit it and the API returns 403 with A public acting-user reference is required for write operations. On catalog reads the header is optional and narrows results to what that user can see.
When to use it
| Scenario | Use X-User-Id |
|---|---|
| A label operations tool creates releases for an artist account | Yes |
| A catalog import maps tracks to the uploader who owns the artist profile | Yes |
| A billing integration manages organization payment methods | No |
| A cross-organization admin tool tries to choose another organization | No |
Request pattern
curl 'https://enterprise.spacemedia.uk/api/v1/releases' \
--header 'Authorization: Bearer 0000000000000000000000000000000000000000963fbb8e' \
--header 'Accept: application/json' \
--header 'X-User-Id: 9d7046b2-3ab1-4c9d-9bd8-90bbd22b7df2'Supported endpoint matrix
Only endpoints listed here accept the header. Anything else ignores it.
| Endpoint | Header | Notes |
|---|---|---|
POST /api/v1/artists | Required | Creates the artist for the acted-for catalog workflow. |
POST /api/v1/artists/{artist_id} | Required | Updates an artist visible to the acted-for user. |
POST /api/v1/releases | Required | Creates the draft release for the acted-for user. |
POST /api/v1/releases/{release_id} | Required | Updates release metadata visible to the acted-for user. |
POST /api/v1/tracks | Required | Creates a track for the acted-for user when the release is visible. |
POST /api/v1/tracks/{track_id} | Required | Updates a visible track. |
POST /api/v1/tracks/upload | Required | Attributes the temporary audio file to the same user who will create the track. |
POST /api/v1/tracks/upload/chunk | Required | Uses the acted-for user as the owner of the resumable upload session. |
GET /api/v1/tracks/upload/{upload_session_id} | Required | Recovers only an upload owned by the same acted-for user, so the header is needed on this read too. |
POST /api/v1/splits | Required | Creates a split in the acted-for workflow. |
GET /api/v1/artists | Optional | Narrows the list to the acted-for user's catalog context. |
GET /api/v1/releases | Optional | Narrows the list to the acted-for user's catalog context. |
GET /api/v1/releases/{release_id} | Optional | Reads a release visible to the acted-for user. |
GET /api/v1/tracks | Optional | Narrows the list to the acted-for user's catalog context. |
GET /api/v1/splits | Optional | Narrows the list to splits visible to the acted-for user. |
| Billing, add-ons, checkouts, theme, account, and review queue endpoints | Not accepted | These use the authenticated organization and credential owner context. |
Use the same X-User-Id for the upload and the track create that follows it. An upload attributed to one user cannot be claimed by a track created for another.
Ownership carryover
When an acted-for request creates a release or track, store the returned release_id or track_id. Later workflow steps should use those public references.
Do not keep sending X-User-Id to later substeps unless that endpoint explicitly documents support for the header. For example, release license, distribution, readiness, and submit calls use the release reference and normal organization access checks.
Rules
- The user must belong to the same organization as the API client.
- Use the public
user_idreturned by the API, never a numeric account reference. - The API client must have the operation's domain capability and
users:act-as. - The endpoint must explicitly support acted-for user context.
- Do not use this header to choose an organization. Organization context comes from authentication.
Next
With authentication settled, move on to the shared request and response rules that apply to every endpoint.
Was this page helpful?