Authentication

A call that acts on your account carries one of your API keys. You create keys in the studio, under Profile → API keys (voplica.com/profile/api-keys); Getting started shows how.

Send the key

Put the key in the Authorization header, with the Bearer scheme:

Authorization: Bearer pat_your_api_key

The pat scheme works too: Authorization: pat pat_your_api_key. Either scheme name may be written in any case. The key is read only from the Authorization header, never from a cookie or another header.

Caution

Your key is a secret. Send it only from your own server, over HTTPS, to https://api.voplica.com.

Your keys

• The format. A key is pat_ followed by 49 letters and digits: 53 characters in all. It carries a checksum, so a mistyped key is refused.
• Shown once. The studio shows a new key only once. Voplica keeps a digest of it, never the key itself, so nobody can show it to you again: if you lose a key, create a new one and delete the old one.
• At most 30 active keys. Expired and revoked keys don’t count.
• An optional expiry. A key expires after 30, 90 or 365 days, or never; In 90 days is preselected. An expired key is refused like a revoked one.
• Revoke or delete. Revoking a key stops it and keeps it in your list, marked revoked. Deleting it stops it and removes it from the list. Apps that use the key stop working within a minute.
• Last used. The API keys page shows when each key was last used.

What a key can do

• A key acts as you. It reads and changes what your account may read and change, and it spends your credits. It has a regular user’s access and never an admin’s, even when your account is an admin’s.
• No scopes, no limits of its own. In this version every key can call every method of the API, and a key has no rate limit of its own.
• Exactly the methods of the reference. A key can call the methods of the API reference (the same methods as the protobuf reference) and no others. Another method refuses it, usually with 403 and permission_denied: API keys cannot call this method.

What only the studio does

These are done in the studio at voplica.com, never with a key:

• your API keys: creating, listing, revoking and deleting them;
• changing your profile and account: the username, the avatar and banner, the account settings, onboarding, deleting the account;
• payments: buying credits and plans, the billing portal and your payment history (a key can read your balance and your credit transactions);
• earnings: applying to the creator program, linking your profiles on other sites and asking for a larger file allowance, payouts and tax forms, revenue share and royalties, the affiliate program;
• prices (the studio’s pricing page);
• support issues, and reporting content;
• tags: listing and creating them, and tagging characters;
• the third-party tokens you save for model imports;
• movies and voices;
• live notifications (the API lists your notifications instead).

Calls without a key

Some methods also answer without a key: the ones whose definition says auth_type: NOT_REQUIRED, which the protobuf reference marks as anonymous. Without a key such a method answers as it would for a signed-out visitor, so it shows only what is public; with your key it answers as you. The OpenAPI document behind the API reference asks for a key on every method, these included.

Errors

HTTP status	code	message	What it means
401	unauthenticated	Authorization failed	The method needs a key and the call has none.
401	unauthenticated	Either token schema or format is invalid	The Authorization header is not Bearer <key> or pat <key>, for example an empty key variable.
401	unauthenticated	Invalid API key	The key is mistyped, unknown, expired, revoked or deleted.
403	permission_denied	API keys cannot call this method	The method is not part of the API.
503	unavailable	Authentication temporarily unavailable	The key could not be checked just now. Retry.

The JSON API lists the other errors.

Keep your keys safe

Never in a web page or a public repository

Anyone who has your key can act as you and spend your credits. Use keys only on servers you control. Never put one in a web page, a browser extension or an app that other people install, where anyone can read it, and never commit one to a repository or post one in public: not in an issue, a discussion, a chat or a screenshot.

• Keep each key in your secret store or in an environment variable, never in your code.
• Give each app its own key, so that you can revoke one without stopping the others.
• If a key leaks, revoke it at once on the API keys page, then create a new key for your app. The leaked key stops working within a minute.
• Voplica’s community forum has the same rule: its Never post list includes API keys.