Get a Key

Every request to the API needs a key. A key belongs to one RandomTranslator account and acts as that account.

Create a key#

You can create a key when:

• you are signed in,
• your account has the Reader membership or higher, with an active pledge, and
• your account is at least a day old.

Open your account page, find API keys, give the key a name you will recognise (up to 40 characters, such as discord bot) and press Create key.

• The key is shown once, with a copy button. Store it then: only a keyed hash is kept, so nobody, us included, can show it to you again.
• A key looks like rtk_ followed by 43 letters, digits, - and _.
• An account can hold up to 3 keys at a time, for example one per tool, and create up to 10 in a day.
• A key lasts one year from its creation; the account page shows when each one expires.
• The account page lists your keys by name, with when each was created and last used. It never shows a key again.

When a key cannot be made, the answer says why:

Keep it safe#

• Send it only in the Authorization header, as Bearer rtk_....
• Keep it out of public code, repositories, web pages and URLs. Call the API from a server, a script, a bot or a browser extension, not from a web page other people load.
• Nothing watches for a leaked key: if yours is exposed, revoke it.

Revoke a key#

Press Revoke next to the key on your account page. It stops at once, everywhere. Keys also appear under Connected apps as "RandomTranslator API key", and Disconnect there revokes the key too.

These also stop a key:

• Sign out everywhere on your account page stops every key and every connected app. Create new keys afterwards.
• A suspended account loses all access.
• A key past its year expires.

All of these answer the same error, 401 invalid_key, on purpose: a revoked key and a mistyped one look alike.

If your membership lapses, your keys are not revoked: they answer 403 membership_required until the membership is active again (checked within a minute), then work as before.

Apps that sign readers in#

An app used by other people, such as an AI assistant, a reading app or a bot that acts for each of its users, should not ask for their keys. It uses OAuth 2.1 instead, the same sign-in the connector uses, and each reader signs in with Patreon and allows it.

• Discovery: https://randomtranslator.com/.well-known/oauth-authorization-server and https://randomtranslator.com/.well-known/oauth-protected-resource/mcp.
• Register: POST https://randomtranslator.com/oauth/register (RFC 7591) with client_name and redirect_uris. Redirect URIs are https, or http on localhost, 127.0.0.1 or [::1]. A mobile or desktop app registers as a public client (token_endpoint_auth_method: "none", the default); a server-side app may ask for client_secret_post or client_secret_basic, and its secret is shown once, in the answer. 30 registrations an hour per address.
• Authorize: send the reader to https://randomtranslator.com/oauth/authorize with response_type=code, client_id, redirect_uri, PKCE (code_challenge with S256; plain is refused), state, scope, and resource=https://randomtranslator.com/mcp. The reader signs in, sees the consent page and presses Allow. A reader without the Reader membership sees a membership page instead, and no code is issued. The redirect carries code, state and iss.
• Token: POST https://randomtranslator.com/oauth/token with grant_type=authorization_code and the code_verifier. Access tokens last 1 hour. Refresh tokens last 60 days and change on every use: always keep the new one, because sending a used refresh token again disconnects the app.
• Revoke: POST https://randomtranslator.com/oauth/revoke (RFC 7009) ends the whole connection.
• Use the token like a key, Authorization: Bearer <access token>, on the connector and on the API routes its permissions allow.

Readers see your app by name under Connected apps on their account page and can disconnect it at any time. Sign out everywhere, a suspension or a lapsed membership affects your app's tokens exactly as it affects keys.

Permissions#

An OAuth app asks for permissions (scope, separated by spaces). The consent page lists them in plain words. Without a scope an app gets all four:

A route outside an app's permissions answers 403 insufficient_scope. A personal key holds all four.