Getting access

There are two kinds of credentials. Every endpoint takes both, unless the reference says otherwise: an API key and secret for your own servers and scripts, and access tokens of a person who signed in to one of our apps.

Your own program: API key and secret

How you get them is described in What you need. Send them with every request as HTTP Basic authentication: the header Authorization: Basic followed by the base64 encoding of key:secret. curl -u KEY:SECRET and every HTTP library do the encoding for you. Add a Recuro-Client header that names your program and its version - it helps us help you:

Authorization: Basic base64(YOUR_API_KEY:YOUR_API_SECRET)
Recuro-Client: my-mam-connector/2.3 (Linux)

For heavy traffic - thousands of chunks - you can exchange the key once an hour for an access token (POST /auth/token with grant_type client_credentials) and send Authorization: Bearer rma_... instead: the secret then travels once an hour, and a token is checked faster. A wrong key and a wrong secret get the same response; 20 failures from one internet address within 15 minutes block that address for up to 15 minutes.

To change the secret, delete it and create a new one (Administrator Tools): requests with the old secret, and the tokens made with it, stop at that moment - put the new secret in place straight away.

Apps: signing in inside the app

Our plugins for Adobe Premiere Pro, DaVinci Resolve and Avid Media Composer (version 1.0, on the Downloads page) let editors sign in and sign up without leaving their editing application, with the website's own rules: POST /auth/login with e-mail address and password (then /auth/login/2fa when the account uses two-factor authentication), /auth/signup with an e-mailed 6-digit code (/auth/signup/verify), a new password by code (/auth/password/forgot, /auth/password/reset), and "E-mail me a code instead" - a sign-in without the password (/auth/login/code, then /auth/login/code/verify; also for accounts made with Google, Apple or Microsoft). Each request names the app: client_id (premiere-uxp, resolve, avid-helper, ofx), client_version, device_name, host_app, host_version and os - the person sees them under Connected Apps. Building an app of your own on this API? Talk to us about a client id. The password is sent once over HTTPS and never stored by the app; only the refresh token is kept, in the operating system's credential store.

Apps: browser sign-in

Accounts made with Google, Apple or Microsoft have no password. Their owners sign in through the website, in their normal browser:

1. The app makes a PKCE verifier (32 random bytes, base64url; it stays in the app) and its S256 challenge (the only one that is sent - the shell lines below make the pair), and starts the sign-in: POST /auth/app-logins.
2. It opens verification_uri_complete in the browser and shows the user_code ("Waiting for your browser - code LRDL-XQTG", with Open browser again and Cancel). The person signs in on the website as always and presses Allow (or Deny). When the browser's internet address differs from the app's, the code must be typed in - a protection against someone else's link.
3. The app polls POST /auth/app-logins/{login_id}/token with its verifier every interval seconds (5): 202 until the person decides, then the tokens, exactly once.
4. After 15 minutes the request expires: the app says "The sign-in was not completed - try again". Cancel: DELETE /auth/app-logins/{login_id}.

VERIFIER=$(openssl rand 32 | base64 | tr '+/' '-_' | tr -d '=')
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=')

Apps: website pages without signing in again

Paying, the order history and the account settings stay on the website. An app the person is signed in to opens them signed in, so nobody has to sign in a second time:

1. Which buttons to show: account of GET /me - Top up... when can_top_up (Prepaid), Upgrade... when can_upgrade (Trial), the billing_note (for example Invoiced monthly) instead, and Order history... on every plan - as well as Open the Website (workspace), Connected Apps (connected_apps) and Contact Support (support).
2. On a click: POST /auth/web-links with the page (top_up, orders, workspace, account, connected_apps or support), and open the url of the answer in the system browser at once. It works once, for 60 seconds, and only while the app's sign-in is live.
3. The browser is signed in (a session of its own: signing out in the browser does not sign the app out) and the page opens. Switching two-factor authentication on (or off) signs every app out, so a link always comes from a sign-in made under the account's current two-factor setting. A link that has expired or was used opens the normal sign-in, then the same page.
4. When the app's window gets the focus back, read GET /me once: a top-up in the browser changes the balance.

The link's secret is in the part of the address after #, which browsers never send to a server, so it is in no server log; the page removes it from the address bar at once. API keys cannot make links - a partner's own program sends its people to the website, where they sign in.

Tokens, refreshing and signing out

• A sign-in gives an access token (rma_..., works 1 hour; keep it in memory) and a refresh token (rmr_..., works 90 days and every refresh starts the 90 days again; keep it in the operating system's credential store). Send the access token as Authorization: Bearer rma_....
• When it expires (TokenExpired), refresh: POST /auth/token with grant_type refresh_token gives a new pair (the old access token stops working at once) - store the new refresh token at once. If the response was lost, the old refresh token works once more within 60 seconds; later it signs the app out (RefreshTokenReused), because someone else must have a copy. At most 30 refreshes an hour.
• The person sees every signed-in app under My Account > Connected Apps and can sign each out there; company administrators can sign out their users' apps in Administrator Tools. A password change or reset, switching two-factor authentication on or off, or a deactivated account signs every app out (TokenRevoked). The app's own Sign out: POST /auth/logout.
• A token never carries more than its person's own rights: nothing in the API manages users, API keys, payments or plans.

Scopes

Each endpoint needs a scope (shown in the reference). API keys have them all; app sign-ins all but webhooks, and they cannot import from an address. A request without the scope answers InsufficientScope.