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

Before creating a connection request, save the developer account callback URL on the API keys page. This callback URL is required and is used as the connection request's redirect_uri.

Do not send redirect_uri in the request body. The API reads it from the developer account tied to the API key. If no callback URL is saved, POST /v1/auth/connections returns redirect_uri_required.

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 "https://api.modusell.com/v1/auth/connections" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --data '{ "state": "RANDOM_CSRF_STATE", "custom_data": { "external_account_id": "acct_123" } }'

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.

custom_data is optional. When present, it must be a JSON object. It is saved on the approved project connection and returned by connection validation/listing responses so your system can carry external IDs or integration context without separate lookup tables.

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 "https://api.modusell.com/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.

Validate Connections

Use GET /v1/auth/connections to list project IDs connected to the current key. Use POST /v1/auth/connections/validate with project_id to verify that the API key can access a specific project.

Validation responses never expose key hashes, raw credentials, developer account sessions, or other sensitive data.

Manage Connections and Keys

Credential operations:

GET /v1/auth/connections
DELETE /v1/auth/connections/{project_id}
POST /v1/auth/api-keys/rotate
POST /v1/auth/api-keys/revoke
Disconnecting a project removes only that key's access to the specified project.
Key rotation returns a replacement raw key once, transfers active project connections, and revokes the previous key.
Key revocation invalidates the key and all project access through it without creating a replacement.

Delete Permission

Project-level delete permission is stricter than normal connected access.

If a project was created through an API key, that API key is the API owner and can delete the project through supported project-delete endpoints.
The ModuSell user who owns the project can delete it from their account.
Other API keys cannot delete that project, even if the user approved a connection for them.
If a project was created directly by a ModuSell user, API keys cannot delete the project. Only the owning user can.