436 lines
13 KiB
YAML
436 lines
13 KiB
YAML
openapi: 3.0.0
|
|
info:
|
|
title: Platform API (Beta)
|
|
version: 1.0.0
|
|
description: |
|
|
**Private Preview** - Contact hey@useautumn.com to get access.
|
|
|
|
The Platform API allows you to manage organizations and Stripe Connect accounts on behalf of your tenants. All endpoints require platform feature access.
|
|
servers:
|
|
- url: https://api.useautumn.com/v1
|
|
security:
|
|
- bearerAuth: []
|
|
paths:
|
|
/platform/organizations:
|
|
post:
|
|
summary: Create Organization
|
|
operationId: createPlatformOrganization
|
|
description: Creates a new organization for a platform tenant. Reuses existing users and organizations if they already exist.
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateOrganizationRequest'
|
|
responses:
|
|
'201':
|
|
description: Organization created successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateOrganizationResponse'
|
|
'400':
|
|
description: Invalid request parameters
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'403':
|
|
description: Platform feature not enabled
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
x-code-samples:
|
|
- lang: curl
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/platform/organizations' \
|
|
-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"
|
|
}'
|
|
get:
|
|
summary: List Organizations
|
|
operationId: listPlatformOrganizations
|
|
description: Lists all organizations created by your master organization. Supports pagination.
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 100
|
|
default: 10
|
|
description: Number of organizations to return (1-100)
|
|
- name: offset
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
default: 0
|
|
description: Number of organizations to skip for pagination
|
|
responses:
|
|
'200':
|
|
description: Organizations retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ListOrganizationsResponse'
|
|
'403':
|
|
description: Platform feature not enabled
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
x-code-samples:
|
|
- lang: curl
|
|
source: |
|
|
curl -X GET 'https://api.useautumn.com/v1/platform/organizations?limit=20&offset=0' \
|
|
-H 'Authorization: Bearer am_sk_test_...'
|
|
|
|
/platform/oauth_url:
|
|
post:
|
|
summary: Generate Stripe OAuth URL
|
|
operationId: generateOAuthURL
|
|
description: Generates a Stripe Connect OAuth URL for a platform organization. Use this to allow your tenants to connect their Stripe accounts.
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GenerateOAuthURLRequest'
|
|
responses:
|
|
'200':
|
|
description: OAuth URL generated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GenerateOAuthURLResponse'
|
|
'400':
|
|
description: Invalid request parameters
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'403':
|
|
description: Forbidden
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'404':
|
|
description: Organization not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
x-code-samples:
|
|
- lang: curl
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/platform/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"
|
|
}'
|
|
|
|
/platform/organizations/stripe:
|
|
post:
|
|
summary: Update Connected Stripe Account
|
|
operationId: updateStripeConfig
|
|
description: Updates a platform organization's Stripe Connect configuration. Associates a Stripe account ID with the organization using your master Stripe credentials.
|
|
security:
|
|
- bearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UpdateStripeConfigRequest'
|
|
responses:
|
|
'200':
|
|
description: Stripe configuration updated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UpdateStripeConfigResponse'
|
|
'400':
|
|
description: Invalid request parameters or validation failed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'403':
|
|
description: Forbidden
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'404':
|
|
description: Organization not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
x-code-samples:
|
|
- lang: curl
|
|
source: |
|
|
curl -X POST 'https://api.useautumn.com/v1/platform/organizations/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"
|
|
}'
|
|
|
|
/platform/users:
|
|
get:
|
|
summary: List Users
|
|
operationId: listPlatformUsers
|
|
description: Lists all users created by your master organization. Supports pagination and optional expansion of related organizations.
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 100
|
|
default: 10
|
|
description: Number of users to return (1-100)
|
|
- name: offset
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
default: 0
|
|
description: Number of users to skip for pagination
|
|
- name: expand
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: "Comma-separated list of fields to expand. Currently supports: 'organizations'"
|
|
responses:
|
|
'200':
|
|
description: Users retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ListUsersResponse'
|
|
'403':
|
|
description: Platform feature not enabled
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
x-code-samples:
|
|
- lang: curl
|
|
source: |
|
|
curl -X GET 'https://api.useautumn.com/v1/platform/users?limit=20&offset=0&expand=organizations' \
|
|
-H 'Authorization: Bearer am_sk_test_...'
|
|
|
|
components:
|
|
schemas:
|
|
CreateOrganizationRequest:
|
|
type: object
|
|
required:
|
|
- user_email
|
|
- name
|
|
- slug
|
|
properties:
|
|
user_email:
|
|
type: string
|
|
format: email
|
|
description: Email address of the organization owner. User will be created if it doesn't exist.
|
|
name:
|
|
type: string
|
|
description: Display name for the organization.
|
|
slug:
|
|
type: string
|
|
description: Unique slug for the organization.
|
|
env:
|
|
type: string
|
|
enum:
|
|
- test
|
|
- live
|
|
- both
|
|
default: both
|
|
description: Environment(s) to create API keys for.
|
|
|
|
CreateOrganizationResponse:
|
|
type: object
|
|
properties:
|
|
test_secret_key:
|
|
type: string
|
|
nullable: true
|
|
description: Autumn test API key for the organization (if env is 'test' or 'both').
|
|
live_secret_key:
|
|
type: string
|
|
nullable: true
|
|
description: Autumn live API key for the organization (if env is 'live' or 'both').
|
|
|
|
GenerateOAuthURLRequest:
|
|
type: object
|
|
required:
|
|
- organization_slug
|
|
- env
|
|
- redirect_url
|
|
properties:
|
|
organization_slug:
|
|
type: string
|
|
description: The slug of the organization.
|
|
env:
|
|
type: string
|
|
enum:
|
|
- test
|
|
- live
|
|
description: "Environment: 'test' or 'live'."
|
|
redirect_url:
|
|
type: string
|
|
format: uri
|
|
description: URL to redirect to after OAuth completion.
|
|
|
|
GenerateOAuthURLResponse:
|
|
type: object
|
|
properties:
|
|
oauth_url:
|
|
type: string
|
|
format: uri
|
|
description: Stripe Connect OAuth URL to redirect the user to.
|
|
|
|
UpdateStripeConfigRequest:
|
|
type: object
|
|
required:
|
|
- organization_slug
|
|
properties:
|
|
organization_slug:
|
|
type: string
|
|
description: The slug of the organization (without the org ID prefix).
|
|
test_account_id:
|
|
type: string
|
|
description: Stripe account ID for test environment (e.g., acct_xxx).
|
|
live_account_id:
|
|
type: string
|
|
description: Stripe account ID for live environment (e.g., acct_xxx).
|
|
|
|
UpdateStripeConfigResponse:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
description: Success message.
|
|
organization:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Internal organization ID.
|
|
slug:
|
|
type: string
|
|
description: Organization slug (without prefix).
|
|
|
|
ListUsersResponse:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/PlatformUser'
|
|
total:
|
|
type: number
|
|
description: Total number of users returned.
|
|
limit:
|
|
type: number
|
|
description: Limit used in the query.
|
|
offset:
|
|
type: number
|
|
description: Offset used in the query.
|
|
|
|
PlatformUser:
|
|
type: object
|
|
properties:
|
|
email:
|
|
type: string
|
|
format: email
|
|
description: User's email address.
|
|
created_at:
|
|
type: number
|
|
description: Timestamp (milliseconds since epoch) when the user was created.
|
|
organizations:
|
|
type: array
|
|
nullable: true
|
|
items:
|
|
$ref: '#/components/schemas/PlatformOrganization'
|
|
description: Array of organization objects (only if expand=organizations is set).
|
|
|
|
ListOrganizationsResponse:
|
|
type: object
|
|
properties:
|
|
list:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/PlatformOrganization'
|
|
total:
|
|
type: number
|
|
description: Total number of organizations returned.
|
|
limit:
|
|
type: number
|
|
description: Limit used in the query.
|
|
offset:
|
|
type: number
|
|
description: Offset used in the query.
|
|
|
|
PlatformOrganization:
|
|
type: object
|
|
properties:
|
|
slug:
|
|
type: string
|
|
description: Organization slug (without master org prefix).
|
|
name:
|
|
type: string
|
|
description: Organization name.
|
|
created_at:
|
|
type: number
|
|
description: Timestamp (milliseconds since epoch) when the organization was created.
|
|
|
|
ErrorResponse:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
description: Error description.
|
|
code:
|
|
type: string
|
|
description: Error code.
|
|
enum:
|
|
- not_found
|
|
- forbidden
|
|
- invalid_input
|
|
- internal_error
|
|
- not_allowed
|
|
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
description: Autumn API key with Bearer prefix
|