> ## Documentation Index > Fetch the complete documentation index at: https://docs.sideshift.app/llms.txt > Use this file to discover all available pages before exploring further. # Record a consent decision > Records the user's allow/deny decision for the chosen company tenant, mints the authorization code on allow, and returns the redirect target. CSRF token and the selected company are validated. Subscription and capability restrictions are enforced when the issued token calls a resource. ## OpenAPI ````yaml /openapi/oauth.yaml post /consent openapi: 3.1.0 info: title: SideShift OAuth API version: 1.0.0 description: | The SideShift OAuth API is a scoped, OAuth 2.1 + OIDC-style authenticated integration surface (served at `/api/oauth/v1`) that lets external apps and AI agents operate a SideShift company on a user's behalf — reading and managing campaigns, contracts, creators, applications, posts, payouts, invoices, messages, and company settings — under explicit, per-scope consent. Every request is bound to the tenant (company) and the exact scopes the user granted, so an integration can only do what it was authorized to do. The same capabilities are also exposed through a remote MCP server at `POST /api/mcp` for AI agents that speak the Model Context Protocol. ### Authentication Access is granted through a standard OAuth flow: 1. **Register a client** with Dynamic Client Registration to obtain a `client_id` (and, for confidential clients, a secret). 2. **Request authorization** via the authorization-code grant with PKCE (`S256`). The user is shown a consent screen and picks the company (tenant) and scopes to grant. 3. **Exchange the code** at the token endpoint for a short-lived bearer access token (and a refresh token). 4. **Refresh** with the refresh-token grant; refresh tokens rotate on every use. See the **OAuth Registration**, **OAuth Authorization**, **OAuth Token**, and **OAuth Discovery** sections for the endpoint details. The protocol follows RFC 6749, 7009, 7591, 7592, 7636, 8414, 9068, and 9728. ### MCP server SideShift also exposes a remote Model Context Protocol (MCP) server at `POST /api/mcp`, using the Streamable-HTTP transport. It fronts the **same** OAuth-scoped capabilities as the REST resources, so an AI agent can operate a SideShift company through MCP tools instead of raw HTTP calls. **Connecting a client.** Point any MCP client at `https://app.sideshift.app/api/mcp`. It authenticates with the **same** OAuth 2.1 flow described above — register a client, run authorization-code + PKCE, and obtain a bearer access token; there is no MCP-specific auth scheme. Tokens minted for MCP are multi-audience, so a single token works for both `/api/oauth/v1` and `/api/mcp`. If a request arrives unauthorized, the server replies `401` with a `WWW-Authenticate` challenge that points at the RFC 9728 protected-resource metadata, letting compliant clients auto-discover the authorization server. **What you get.** Every capability scope maps to tools, and the tool set mirrors the REST surface plus a `whoami` tool. Read scopes expose read-only tools; write and sensitive tools carry a confirmation guardrail in their description. Sensitive tools — those that move money or trigger outbound side-effects — are rejected for sandbox/test grants and can be globally disabled with the `MCP_SAFE_MODE` server flag. The claim-link capability is available as the `create_quickpay_claim_link` tool. ### Conventions - **Pagination** — list endpoints return `{ data, nextCursor, hasMore }`. Pass the opaque `cursor` from `nextCursor` to fetch the next page, plus an optional `limit` (default 25, max 100). - **Errors** — every error response uses the envelope `{ error: { code, message, requestId } }`. Include `requestId` when contacting support. - **Idempotency** — an `Idempotency-Key` header is honored on every POST, PATCH, and PUT, and is **required** on money-moving writes so a retried request never double-charges. - **Rate limiting** — every response carries `X-RateLimit-*` headers, and a `WWW-Authenticate` header accompanies 401 and 403 responses. ### Sandbox & sensitive operations Test/sandbox grants can exercise reads and safe writes, but requests that move money or trigger outbound side-effects (payouts, sending invoices or messages, external re-scrapes) are rejected. Money-moving endpoints and campaign analytics-history validation/import requests require an `Idempotency-Key`. contact: name: SideShift API url: https://app.sideshift.app servers: - url: https://app.sideshift.app/api/oauth/v1 description: Production security: - oauth2: [] tags: - name: Campaigns description: Programs/campaigns and their payment structures. - name: Contracts description: Creator contracts. - name: Creators description: Creator roster, collections, and campaign invites. - name: Applications description: Campaign applications (creator handle requests) and their review. - name: Posts description: Tracked creator posts, their metrics history, and CSV export. - name: Payouts description: >- Payout history and pending-payout calculations, plus executing contract payouts, one-time and custom bonuses, and Quick Pay. - name: Invoices description: Invoices — list, get, create, send, and void. - name: Messages description: > Direct-message conversations: list the company's conversations, read a conversation's messages, and send a message (as the company). Messages are delivered via the company's connected chat when available and always persisted; a single conversation is bound to the token's company tenant. - name: Settings description: > Company settings and profile. `GET/PATCH /settings` exposes a server-side **allowlist** of mutable fields (profile/contact/socials/signing); reads and writes never include plan, billing, subscription, permissions, credits, or verification fields. `GET /company` returns the read-only company profile. - name: Invites description: > Campaign/program invite links — list, create, and revoke shareable invites that let creators join a campaign. Team-member invites are managed under the Team tag. - name: OAuth Registration description: > Dynamic Client Registration (RFC 7591) and client configuration management (RFC 7592). Open registration is per-IP rate-limited; management requires the one-time `registration_access_token` returned at registration. - name: OAuth Authorization description: > The authorization endpoint (RFC 6749 §4.1, PKCE S256 required) and the in-session consent bridge that records the user's tenant + scope grant and mints the authorization code. - name: OAuth Token description: > Token issuance (RFC 6749: authorization_code, refresh_token, client_credentials) and revocation (RFC 7009). Form-encoded; responses are `no-store`. - name: OAuth Discovery description: > Public discovery documents — authorization-server metadata (RFC 8414), protected-resource metadata (RFC 9728), and the signing-key JWKS. - name: Agencies description: > Agency-level management for parent companies and their client subaccounts — dashboards, cross-account creator and program rollups, per-client billing, and payout cashflow forecasting. - name: Applicants description: > Review and manage the people who apply to a company's jobs: filter and list applicants, view counts and top posts, bookmark, update status, export to CSV, and open applicant support channels. - name: Billing description: > Subscription and payment-method management — view billing history and subscription status, set the default payment method, preview plan changes, cancel a subscription, and mint browser billing handoff links. - name: Booking description: >- Booking-calendar configuration for scheduling calls with creators and agencies. - name: Brand Content Pages description: > Create, update, and list a company's brand content pages — the public pages that present the brand to creators. - name: Brand Livestream description: Brand live-stream events and their configuration. - name: Brand Verification description: Check a company's brand-verification status. - name: Community Courses description: Educational courses published to a brand's creator community. - name: Community Offers description: Promotional offers and deals published to a brand's creator community. - name: Companies description: > Manage the companies (and agency subaccounts) a user belongs to — create and list companies, read and update company and invoicing profiles, and propagate name, logo, and niche changes across programs and jobs. - name: Conversations description: > Manage direct-message conversations — create threads, add or remove group members, rename, forward messages, and add reactions. - name: Creator Collections description: Organize creators into named collections and manage their membership. - name: Discover description: > The Discover marketplace surface — publish and manage a company's Discover listing, handle qualified lead-form submissions, configure booking hosts, and message agencies. - name: Disputes description: >- View and resolve creator-payment disputes, including uploading counter-evidence. - name: Integrations description: > Connect and configure third-party integrations such as Slack — manage channels, workflow templates, OAuth connections, and test deliveries. - name: Jobs description: >- Post and manage marketplace job listings — create, update, boost, repost, and change job status. - name: Performance description: >- Brand-facing performance observability + creator matching (manually provisioned — SideShift must enable the Performance API for the company). - name: Quick-Pay description: > Send fast, wallet-funded payments to creators — claim links, approval workflows, recurring schedules, reusable templates, and drafts. - name: Recruit description: > Search for and recruit creators — browse candidate profiles, bookmark prospects, and send recruitment invites. - name: Team description: > Manage a company's team — list members and seat usage, invite new members, update permissions and roles, and remove members. - name: Wallet description: > View and move funds in a company's wallet — balances, ledger history, and transfers between an agency and its subaccounts. - name: Video Submissions description: > Review creator video submissions for a company's campaigns, and remove submissions along with the posts they created. - name: Analytics description: Analytics operations. - name: Verifications description: Read identity verification status, profile details, and required actions. paths: /consent: post: tags: - OAuth Authorization summary: Record a consent decision description: > Records the user's allow/deny decision for the chosen company tenant, mints the authorization code on allow, and returns the redirect target. CSRF token and the selected company are validated. Subscription and capability restrictions are enforced when the issued token calls a resource. operationId: postConsent requestBody: required: true content: application/json: schema: type: object required: - request_id - csrf_token - company_id - decision properties: request_id: type: string csrf_token: type: string company_id: type: string description: The tenant the grant is bound to. decision: type: string enum: - allow - deny granted_scopes: type: array description: >- Subset of the requested scopes the user approved (allow only). items: type: string example: request_id: areq_3b2a... csrf_token: csrf_7f1e... company_id: Dsc8SfHtPjzNGDKzMqBP decision: allow granted_scopes: - campaigns:read - contracts:read - offline_access responses: '200': description: The redirect target for the browser to follow back to the client. content: application/json: schema: type: object properties: redirect: type: string format: uri decision: type: string enum: - allow - deny example: redirect: >- https://acme.example.com/oauth/callback?code=ac_...&state=xyz987&iss=https://app.sideshift.app decision: allow '400': $ref: '#/components/responses/OAuthSessionError' '401': $ref: '#/components/responses/OAuthSessionError' '402': $ref: '#/components/responses/OAuthSessionError' '403': $ref: '#/components/responses/OAuthSessionError' '404': $ref: '#/components/responses/OAuthSessionError' '409': $ref: '#/components/responses/OAuthSessionError' '410': $ref: '#/components/responses/OAuthSessionError' security: - firebaseSession: [] components: responses: OAuthSessionError: description: > A consent-endpoint error. These are in-session (not RFC 6749): `{ error, message }` where `error` is one of `invalid_request` (400), `unauthorized` (401), `subscription_required` (402), `forbidden`/`csrf` (403), `not_found` (404), `already_used` (409), or `expired` (410). content: application/json: schema: type: object required: - error properties: error: type: string message: type: string example: error: expired message: This authorization request has expired securitySchemes: oauth2: type: oauth2 description: > OAuth 2.1 authorization code + PKCE (S256). Tokens are tenant-bound (`company_id`) and scoped. Discover endpoints via `/.well-known/oauth-authorization-server`. flows: authorizationCode: authorizationUrl: https://app.sideshift.app/api/oauth/v1/authorize tokenUrl: https://app.sideshift.app/api/oauth/v1/token refreshUrl: https://app.sideshift.app/api/oauth/v1/token scopes: campaigns:read: Read campaigns and payment structures campaigns:write: Create/update/archive campaigns and payment structures applications:read: Read campaign applications (handle requests) applications:write: Approve/reject campaign applications contracts:read: Read contracts contracts:write: Create and cancel contracts creators:read: Read creators and collections creators:write: Create collections and campaign invites posts:read: Read tracked posts, their metrics history, and exports payouts:read: Read payout history, pending payouts, and wallet stats payouts:write: Execute contract payouts and Quick Pay (sensitive — moves money) invoices:read: Read invoices invoices:write: Create, send, and void invoices messages:read: Read conversations and messages messages:write: Send messages settings:read: Read company settings and profile settings:write: >- Update company settings (allowlisted) and create/revoke invites (sensitive) offline_access: Optional OIDC signal for offline access agencies:write: >- Update agency program/contract/client notes, program status, and client archive status agencies:read: >- Read agency dashboard, client lists, creator details, and payment receipts agency-billing:write: >- Update agency billing info, generate subscription links, toggle separate subs, and assign free clients — this moves money. agency-billing:read: Read your agency billing configuration. applicants:read: >- Read access to applicants, including filtered lists, counts, and export applicants:write: >- Write access to update applicant status, bookmarks, and resolve support channels billing:write: >- Manage subscription, payment methods, and bank accounts — this changes what you are charged. billing:read: >- Read subscription status, payment methods, bank-account status, and upgrade previews. booking:write: >- Create and modify bookings, send booking requirements, and other write operations brand-content-pages:read: >- List and view brand content pages (public published pages visible to all, drafts visible to writers only) brand-content-pages:write: >- Create, update, and manage brand content pages (create drafts, publish, manage public share tokens) brand-livestream:write: >- Start/end livestreams, mint viewer tokens, rotate stream keys, and manage egress. brand-livestream:read: >- Read active livestreams, recordings, and settings for brand livestreams. brand-livestream:settings: Update chat and moderation settings for brand livestreams. brand-verification:write: Create brand verification requests and prepare document uploads brand-verification:read: Read access to brand verification status and request history brand-performance:read: >- Read own campaign spend/delivery health and creator-match shortlists (manually provisioned — SideShift must enable the Performance API) agency-performance:read: >- Read performance data for every client brand in your agency subtree — health, scorecards, creator relationships, and a portfolio rollup (agency accounts; manually provisioned) community-courses:read: Read-only access to community course content and metadata community-courses:write: >- Create, update, and delete community courses (educational content management) community-offers:checkout: >- Create checkout sessions for community offer purchases (involves payment processing) community-offers:write: >- Create, update, and delete community offers, promo codes, and Discord integration settings community-offers:membership: >- Link and resolve community offer memberships from purchases (involves payment processing) community-offers:read: Read community offers, promo codes, and membership data discover:read: Read your Discover marketplace offer/listing. discover:write: Publish, update, or remove your Discover marketplace offer. disputes:write: >- Resolve disputes and submit counter-evidence — this can move money. disputes:read: Read creator-payment disputes and their evidence. integrations:read: Read Slack integrations, channels, templates, and configuration integrations:write: >- Create, update, and delete Slack integrations, channels, templates, and workflows jobs:write: >- Create new jobs and update existing jobs, including changing posting status, reposts, and job management. Costs job posting credits for new jobs. jobs:read: >- List and read job data, including duplicate target companies. Read-only access to job details. quick-pay:write: >- Create/update/send Quick-Pay drafts, schedules, templates, and approvals — sending moves money to creators. quick-pay:read: >- Read Quick-Pay drafts, schedules, templates, approvals, pending payments, and recent recipients. recruit:read: Search recruit students and view bookmarked recruits recruit:write: Send recruit invites, manage bookmarks, and mint action tokens team:read: >- Read access to team members list and company invites. Allows viewing member details, permissions, and pending invitations. team:write: >- Write access to add, remove, and update team members, and create/send team invitations. wallet:read: Read your company/agency wallet balance, summary, and ledger. wallet:write: >- Top up (Stripe/bank transfer), reconcile, transfer balance, and record ledger entries — this moves money. video-submissions:write: >- Approve, reject, or request revisions on video submissions, and delete submissions. video-submissions:read: >- Read creator video submissions for your campaigns, including review status. posts:write: >- Set post approval status, mark/clear deletion, and manage analytics tags. booking:read: Read creator booking settings, booking intents, and service types. analytics:read: Read analytics and performance data. verification:read: >- Read your identity verification status, profile, and required actions. firebaseSession: type: http scheme: bearer bearerFormat: JWT description: > The end-user's Firebase session token. Used only by the in-session consent endpoints (`/consent`), which run inside the SideShift web app. ````