Connect a Project

The API client cannot choose a project directly. Project access begins only after a ModuSell user logs in and approves one of their projects.

Create a Connection Request

Generate a cryptographically random state value and call POST /v1/auth/connections with the global API key as an Authorization bearer credential.

bash

curl --request POST "$BASE_URL/v1/auth/connections" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{ "state": "RANDOM_CSRF_STATE" }'

The response includes a short-lived connection_token, connection_url, and expires_at. Store the token securely and redirect the user's browser to connection_url.

ModuSell Authorization

The connection URL opens on www.modusell.com. If the user is not signed in, ModuSell sends them to login and returns them to the connection screen afterward. The screen lists only projects owned by that user. The user selects one and chooses Connect project.

Handle the Callback

ModuSell redirects the browser to the developer account's registered callback URL:

text

https://developer.example.com/callback?code=ONE_TIME_CODE&state=RANDOM_CSRF_STATE

Reject the callback if state does not exactly match the value stored when the connection began. If the user cancels, the callback contains error=access_denied and the original state.

Save the Connection

After validating state, complete the connection with the same API key:

bash

curl --request POST "$BASE_URL/v1/auth/connections/complete" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{ "code": "ONE_TIME_AUTHORIZATION_CODE" }'

This stores the selected project as a durable connection under the API key. Completing another authorization with the same key adds another project connection; it does not bind the key to only one project.