Authentication & Security
How StockFlow protects your account, manages access, and keeps your media library safe.
Every integration with StockFlow — whether a browser-based app, a CLI tool, or a background download service — goes through one of two authentication paths: OAuth 2.0 for interactive client applications, or API keys for server-to-server workflows. Both methods enforce token expiration, IP allowlisting, and per-scope rate limits.
OAuth 2.0
Authorization Code Flow with PKCE
StockFlow implements the OAuth 2.1 recommendation: Authorization Code + PKCE (Proof Key for Code Exchange). When a user clicks "Sign in with StockFlow" inside your application, they are redirected to https://auth.stockflow.ru/oauth/authorize with your client ID, a randomly generated code verifier, and a list of requested scopes. After the user consents, StockFlow returns a short-lived authorization code to your redirect URI. You exchange that code for an access token (valid 60 minutes) and a refresh token (valid 90 days) by POSTing to https://api.stockflow.ru/oauth/token with your client secret and the original code verifier.
Access tokens are JSON Web Tokens signed with RS256. You can validate them locally using the public key published at https://auth.stockflow.ru/.well-known/jwks.json. Refresh tokens are opaque, single-use, and rotate on every call — the old refresh token is invalidated the moment a new one is issued. If a refresh token is used on a different IP address than the one that obtained it, StockFlow revokes the entire token pair and sends a security alert to the account owner.
Authorization Endpoint
GET https://auth.stockflow.ru/oauth/authorize
Supports response_type=code, code_challenge, and code_challenge_method=S256. State parameter is mandatory — StockFlow rejects requests that omit it.
Token Endpoint
POST https://api.stockflow.ru/oauth/token
Accepts grant_type=authorization_code and grant_type=refresh_token. Returns access_token, refresh_token, expires_in, and scope.
Revocation Endpoint
POST https://api.stockflow.ru/oauth/revoke
Accepts either an access token or a refresh token. Immediately invalidates the token and, for refresh tokens, the associated pair.
API Keys
Server-Side API Key Management
For non-interactive services — batch downloads, automated metadata sync, CI/CD pipelines — StockFlow issues static API keys. Each key is a 48-character Base62 string prefixed with sf_live_ (production) or sf_test_ (sandbox). Keys are created in the developer dashboard under Settings → API Keys and can be scoped to a subset of permissions at creation time.
Best practice: rotate keys every 90 days. StockFlow supports dual-key rotation — create the new key before revoking the old one so both are valid during the transition window. You can also bind a key to a CIDR block (e.g., 203.0.113.0/24); requests originating outside that range are rejected with HTTP 403. Every API key has a per-minute rate limit that depends on the subscription tier: Starter (30 req/min), Professional (120 req/min), Enterprise (500 req/min). Rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.
Key Format
Production keys: sf_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGh
Sandbox keys: sf_test_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGh
Keys are transmitted only over TLS 1.2+ and must be placed in the Authorization: Bearer header or the X-StockFlow-Key header.
Rotation Workflow
1. Generate a new key in the dashboard.
2. Update your service configuration to use the new key.
3. Verify the new key works by calling GET /v2/health.
4. Revoke the old key — StockFlow waits 15 minutes before hard deletion to allow in-flight requests to complete.
Audit Log
Every API key action — creation, rotation, revocation, and every request made with the key — is recorded in the Audit Log. Entries include timestamp, IP address, user-agent, endpoint, HTTP method, and response status. Logs are retained for 365 days and can be exported as JSON via the dashboard or the GET /v2/audit-log endpoint.
Access Levels
Scopes and Permission Matrix
StockFlow uses a fine-grained scope system. When a user authorizes your application or when you create an API key, you request only the scopes your integration needs. The platform enforces the principle of least privilege — a token with media:read cannot delete assets or modify billing information.
media:read
Search the catalog, view clip metadata, download preview thumbnails, and stream watermarked previews. Required for any read-only browsing or search integration. Does not grant access to original-resolution files.
media:download
Download original-resolution clips and audio stems. Tracks download counts against the account's monthly quota. Each download generates a signed URL valid for 15 minutes, limited to a single IP address.
media:upload
Upload new clips, set metadata, assign tags, and manage collections. Used by contributor dashboards and asset-management tools. Uploaded files are scanned for malware and checked against the Content ID database before becoming visible.
media:delete
Permanently remove uploaded clips and empty collections. This scope is restricted to account owners and explicitly granted team members. Deletion is soft for the first 30 days; a restore endpoint is available during that window.
account:read
View account details, subscription tier, usage statistics, and billing history. Does not expose payment card numbers — only the last four digits and expiry month/year.
account:write
Update profile information, change the account email, manage team members, and adjust notification preferences. Cannot change the billing address or payment method — a separate billing:write scope is required for that.
Scopes are additive. A token with media:read media:download can search and download but cannot upload or delete. If an application requests a scope the user has not consented to, StockFlow returns HTTP 403 with a scope_denied error code. Administrators can audit every granted scope across all installed applications from Settings → Connected Apps and revoke access instantly.
For questions about authentication, integration support, or security audits, contact our developer relations team at security@stockflow.ru. Our security advisory program is documented at https://stockflow.ru/security.