cfw-autumn/server/src/internal/platform/platformBeta/PLATFORM_API.md

Platform API Reference

The Platform API allows you to manage organizations and Stripe Connect accounts on behalf of your tenants. All endpoints require platform feature access.

Authentication

All Platform API endpoints require:

• Valid Autumn API key in the Authorization header
• Platform feature enabled for your organization

Authorization: Bearer am_sk_test_...

---

Endpoints

POST /v1/platform/beta/organization

Creates a new organization for a platform tenant. Reuses existing users and organizations if they already exist.

Request Body:

Parameter	Type	Required	Description
user_email	string	Yes	Email address of the organization owner. User will be created if it doesn't exist.
name	string	Yes	Display name for the organization.
slug	string	Yes	Unique slug for the organization (will be prefixed with your org ID).
env	enum	No	Environment(s) to create API keys for: "test", "live", or "both". Defaults to "both".

Response:

Field	Type	Description
test_secret_key	string?	Autumn test API key for the organization (if env is "test" or "both").
live_secret_key	string?	Autumn live API key for the organization (if env is "live" or "both").

Example:

curl -X POST https://api.useautumn.com/v1/platform/beta/organization \
  -H "Authorization: Bearer am_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_email": "tenant@example.com",
    "name": "Tenant Organization",
    "slug": "tenant-org",
    "env": "both"
  }'

Response:

{
  "test_secret_key": "am_sk_test_abc123...",
  "live_secret_key": "am_sk_live_xyz789..."
}

Notes:

• If a user with the email already exists, it will be reused
• If an organization with the slug already exists for this user, it will be reused
• The actual organization slug stored will be {slug}_{your_org_id} to ensure uniqueness
• Returns Autumn API keys that your tenant can use to interact with Autumn

---

POST /v1/platform/beta/oauth_url

Generates a Stripe Connect OAuth URL for a platform organization. Use this to allow your tenants to connect their Stripe accounts.

Request Body:

Parameter	Type	Required	Description
organization_slug	string	Yes	The slug of the organization (without the org ID prefix).
env	enum	Yes	Environment: "test" or "live".
redirect_url	string	Yes	URL to redirect to after OAuth completion.

Response:

Field	Type	Description
oauth_url	string	Stripe Connect OAuth URL to redirect the user to.

Example:

curl -X POST https://api.useautumn.com/v1/platform/beta/oauth_url \
  -H "Authorization: Bearer am_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "organization_slug": "tenant-org",
    "env": "test",
    "redirect_url": "https://yourapp.com/stripe/callback"
  }'

Response:

{
  "oauth_url": "https://connect.stripe.com/oauth/v2/authorize?response_type=code&client_id=ca_xxx&scope=read_write&state=abc123&redirect_uri=https://express.dev.useautumn.com/stripe/oauth_callback"
}

OAuth Flow:

1. Call this endpoint to get the OAuth URL
2. Redirect your tenant to the oauth_url
3. User authorizes their Stripe account
4. Stripe redirects to Autumn's callback URL
5. Autumn processes the authorization and redirects to your redirect_url
6. Your redirect_url will receive query parameters:
   • success=true or success=false
   • message=... (if error occurred)

Notes:

• OAuth state is stored in Upstash with 10-minute expiry
• The organization must have been created via the platform API
• After successful OAuth, the Stripe account is automatically linked to the tenant organization

---

POST /v1/platform/beta/organization/stripe

Updates a platform organization's Stripe Connect configuration. Associates a Stripe account ID with the organization using your master Stripe credentials.

Request Body:

Parameter	Type	Required	Description
organization_slug	string	Yes	The slug of the organization (without the org ID prefix).
test_account_id	string	No*	Stripe account ID for test environment (e.g., acct_xxx).
live_account_id	string	No*	Stripe account ID for live environment (e.g., acct_xxx).

*At least one of test_account_id or live_account_id must be provided.

Response:

Field	Type	Description
message	string	Success message.
organization.id	string	Internal organization ID.
organization.slug	string	Organization slug (without prefix).

Example:

curl -X POST https://api.useautumn.com/v1/platform/beta/organization/stripe \
  -H "Authorization: Bearer am_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "organization_slug": "tenant-org",
    "test_account_id": "acct_1234567890",
    "live_account_id": "acct_0987654321"
  }'

Response:

{
  "message": "Stripe Connect configuration updated successfully",
  "organization": {
    "id": "org_abc123",
    "slug": "tenant-org"
  }
}

Validation:

• Your organization must have the corresponding Stripe secret key connected (test/live)
• The endpoint validates that your master Stripe account can access the provided account ID
• If validation fails, you'll receive a descriptive error message

Notes:

• Use this endpoint when you want to manage Stripe accounts on behalf of your tenants using your own Stripe Connect credentials
• The master_org_id is automatically set to your organization ID
• All Stripe operations for the tenant will use your master Stripe credentials with the tenant's account ID
• This is an alternative to the OAuth flow for cases where you have direct access to the tenant's Stripe account ID

---

Error Responses

All endpoints return standard error responses:

{
  "message": "Error description",
  "code": "error_code"
}

Common Error Codes:

Code	Status	Description
not_found	404	Organization not found or doesn't exist.
forbidden	403	You don't have permission to manage this organization.
invalid_input	400	Invalid request parameters or missing required fields.
internal_error	500	Internal server error.
not_allowed	403	Platform feature not enabled for your organization.

Example Error Response:

{
  "message": "Organization with slug 'tenant-org' not found",
  "code": "not_found"
}

---

Rate Limits

Platform API endpoints share the same rate limits as other Autumn API endpoints. Contact support if you need higher rate limits.

---

Support

For questions or issues with the Platform API, contact:

• Email: hey@useautumn.com
• Documentation: https://docs.useautumn.com