🔑 Authentication

All requests must be made over HTTPS and will be authenticated using an API key. To create your first API Key, please use the AudioStack Platform.

🚧

Keep your API keys secret!

They should not be added to the client-side code or checked into your application's code, including through repositories such as Github.

import audiostack
import os
 
audiostack.api_key = os.environ["AUDIO_STACK_DEV_KEY"]

Code Examples

Get your first audio project started with the below example. This is also useful for debugging if your API key is working.

Create a script

This creates a project called myFirstAudioProject with one module admodule under which you'll find your first script.

curl -X 'POST' \
  'https://v2.api.audio/content/script' \
  -H 'accept: application/json' \
  -H 'x-api-key: APIKEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "projectName": "myFirstAudioProject",
  "moduleName": "admodule",
  "scriptName": "script1",
  "scriptText": "Got my first script created!"
}'

Retrieve uploaded custom audio files

curl --request GET \
     --url 'https://v2.api.audio/content/media' \
     --header 'Accept: application/json' \
     --header 'x-api-key: APIKEY'

Multi-Organization API Access Guide

Overview

This guide explains how to work with the AudioStack API when your account belongs to more than one organization. It covers the x-assume-org header, common error patterns, and best practices for avoiding permissions issues.

1. How Organizations Work

Every AudioStack user belongs to at least one organization. An organization is typically your company or team. Resources you create — audioforms, stories, sound templates, etc. — are owned by the organization that was active when you created them.

When your account is associated with a single organization, the API automatically scopes all requests to that org. No extra configuration is needed.

When your account is associated with multiple organizations, the API must know which org context to use for each request. Without explicit instruction, it falls back to your default organization. If the resource or endpoint you are targeting belongs to a different org, the API denies the request.

Key concepts

2. The Problem: 403 "Access denied. Invalid org permissions."

When making API requests, you may receive a 403 error:

{
  "message": "Access denied. Invalid org permissions."
}

Or, wrapped by a client-side handler:

{
  "message": "Story API request failed with status 403",
  "error": "{ \"message\": \"Access denied. Invalid org permissions.\" }"
}

Why this happens

The API validated your API key successfully (otherwise you would get a 401 Unauthorized), but the organization context of the request does not match the organization that owns the resource or endpoint. This means:

1. Your API key is valid.
2. The org the API is using for the request does not have permission to access what you asked for.

Common scenarios that trigger this error

3. The Fix: Use the x-assume-org Header

Include the x-assume-org header in your API requests, set to the Organization ID that owns the resource or endpoint you are calling.

Example: cURL

curl -X GET "https://v2.api.audio/audioforms/{audioformId}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-assume-org: my-team-a1b2-c3d4"

Example: POST request (creating a story)

curl -X POST "https://v2.api.audio/creator/story" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-assume-org: my-team-a1b2-c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "scriptText": "Your story content here..."
  }'

Example: Python (requests)

import requests

headers = {
    "x-api-key": "YOUR_API_KEY",
    "x-assume-org": "my-team-a1b2-c3d4",
    "Content-Type": "application/json",
}

response = requests.get(
    "https://v2.api.audio/audioforms/{audioformId}",
    headers=headers,
)

Example: JavaScript (fetch)

const response = await fetch(
  "https://v2.api.audio/audioforms/{audioformId}",
  {
    method: "GET",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "x-assume-org": "my-team-a1b2-c3d4",
      "Content-Type": "application/json",
    },
  }
);

4. Finding Your Organization ID

1. Log in to the AudioStack dashboard.
2. Navigate to Settings > Organization (or the equivalent section).
3. Copy the Organization ID — it will look something like my-team-a1b2-c3d4.

If you belong to multiple orgs, you will see each one listed. Make sure you select the org that owns the resource you are trying to access.

Tip: If you are unsure which org a resource belongs to, check where (and by whom) it was originally created. Resources are always tied to the org that was active at the time of creation.

5. Best Practices

Always send x-assume-org explicitly

Even if your API key currently defaults to the correct org, explicitly setting the header protects you against:

• Future changes to your default org.
• Key rotation where the new key has a different default.
• Teammates using different keys with different defaults.

Set it once in your HTTP client configuration

Rather than adding the header to every individual request, configure it at the client or session level:

import requests

session = requests.Session()
session.headers.update({
    "x-api-key": "YOUR_API_KEY",
    "x-assume-org": "my-team-a1b2-c3d4",
})

# All requests through this session will include the header
response = session.get("https://v2.api.audio/audioforms/{audioformId}")

Use environment variables for org IDs

Avoid hardcoding Organization IDs. Store them alongside your API key:

export AUDIOSTACK_API_KEY="your-api-key"
export AUDIOSTACK_ORG_ID="my-team-a1b2-c3d4"

import os

headers = {
    "x-api-key": os.environ["AUDIOSTACK_API_KEY"],
    "x-assume-org": os.environ["AUDIOSTACK_ORG_ID"],
}

Keep org IDs consistent across environments

If you use separate orgs for staging and production, make the org ID part of your environment configuration so it cannot be accidentally swapped:

6. Troubleshooting Checklist

Use this step-by-step checklist when you encounter a 403 org permissions error:

7. Summary of Required Headers

For multi-org API access, every request should include:

x-api-key: YOUR_API_KEY
x-assume-org: YOUR_ORGANIZATION_ID
Content-Type: application/json          (for POST/PUT/PATCH requests)

8. FAQ

Q: Do I need this header if I only belong to one organization?
A: No. The header is only required when your API key is associated with multiple organizations. If you belong to a single org, requests are automatically scoped to it. However, adding it anyway does no harm and future-proofs your integration.

Q: I'm sending the header but still getting a 403.
A: Double-check:

• The Organization ID is spelled correctly (case-sensitive).
• Your API key actually has access to that organization.
• The resource you are accessing was created under the org you are specifying.
• You are not accidentally overriding the header elsewhere in your code (e.g., a middleware or interceptor).

Q: I switched API keys and the error went away. Why?
A: Different API keys can have different default organizations. The new key likely defaults to the correct org, making the x-assume-org header unnecessary. However, relying on key defaults is fragile — always set the header explicitly.

Q: Does this apply to all API versions and endpoints?
A: Yes. The x-assume-org header is supported across API versions (v1 and v2) and all endpoints, including /audioforms, /creator/story, and others.

Q: Can I switch orgs mid-session or mid-workflow?
A: Yes. The x-assume-org header is evaluated per-request. You can target different orgs in consecutive requests by changing the header value. There is no persistent session state to reset.

Q: What is the difference between a 401 and a 403 in this context?
A: A 401 Unauthorized means your API key is invalid or missing. A 403 Forbidden with the "Invalid org permissions" message means your key is valid but the org context is wrong. If you see a 401, fix your API key first before troubleshooting org headers.