Connect Estii accounts

Your users click Connect Estii in your product, sign in to Estii, approve the access you asked for, and your platform receives tokens that call the Estii API as that user.

What to ask Estii for

Ask your Estii contact for an OAuth client, and send:

• your product name, as users should see it when they approve
• the exact redirect URI(s) your platform uses for OAuth callbacks, HTTPS only
• the scope you need: read or read_write
• your privacy policy URL and a support contact

You receive a client_id and a client_secret. The secret is shown once; store it as you would any API secret. A test client and a live client are issued separately.

Endpoints

Discovery document: https://api.estii.com/.well-known/oauth-authorization-server

Flow

1. Send the user's browser to the authorization endpoint with response_type=code, your client_id, your registered redirect_uri, the scope you were issued, and a random state. PKCE (code_challenge with code_challenge_method=S256) is recommended.
2. The user signs in to Estii and approves. Estii redirects to your redirect_uri with code, your state unchanged, and iss=https://api.estii.com. If the user denies, the redirect carries error=access_denied instead.
3. Within ten minutes, exchange the code at the token endpoint, once: presenting a code a second time ends the connection it created. Send a POST with Content-Type: application/x-www-form-urlencoded carrying grant_type=authorization_code, code, redirect_uri, your client credentials (client_id and client_secret in the body, or HTTP Basic), and code_verifier if you sent a challenge.
4. The response is JSON with access_token, token_type, expires_in, scope, refresh_token and resource.

Call the API with Authorization: Bearer <access_token>. GET /v1/spaces lists the spaces the user can reach and doubles as a connection test.

Tokens

• Access tokens last one hour.
• Refresh tokens last 30 days from their last use. Refresh with grant_type=refresh_token, refresh_token and your client credentials. Each refresh returns a new refresh token; the old one stops working once the new one is used.
• A refresh token that has expired or been revoked answers 400 with error: "invalid_grant". Send the user through Connect again.
• A user can disconnect your platform from their Estii account settings. The next API call answers 401.
• To disconnect from your side, POST the refresh token as token to the revocation endpoint with your client credentials.

Scopes

A write also needs the user's space to be on a paid plan or a trial: on a free space it answers 402 with plan_required and an upgrade URL. Reads work on every plan. A write with a read token answers 403 with error="insufficient_scope" in the WWW-Authenticate header.

Rate limits and errors

Each connected user is limited as any credential is, with the same error shapes (Authentication). A 401 on an API call means the access token has expired or was revoked: refresh, then retry once.

Before you ship

• The redirect URI registered with Estii matches yours exactly, path and trailing slash included.
• state round-trips unchanged and you check it on return.
• Token requests are form-encoded, not JSON.
• invalid_grant on refresh sends the user back through Connect, not into a retry loop.
• Your disconnect revokes the refresh token.
• Tokens are never logged or shown to users.