Providers & OAuth

Operations on this page

Operation	Method and path	Python	Node.js
List providers	`GET /api/v2/integrations/providers`	`providers.list`	`providers.list`
Get one provider	`GET /api/v2/integrations/providers/{provider_id}`	`providers.get`	`providers.get`
Start authorisation	`POST /api/v2/integrations/oauth/initiate`	`connections.oauth.initiate`	`connections.oauth.initiate`
Which providers are configured	`GET /api/v2/integrations/oauth/status`	`connections.oauth.status`	`connections.oauth.status`

Authentication and scope

Requirement	Contract
Credential	An API key sent as `X-API-Key`. Connector operations are not end-user scoped.
Read scope	`integrations:read` for every `GET`.
Write scope	`integrations:write` for every `POST`, `PUT`, `PATCH` and `DELETE`.
Tenant	Derived from the authenticated key. There is no tenant parameter to pass or to get wrong.
`X-End-User-ID`	Not used. A connection belongs to the organization, not to one end user.

1. Ask what can be connected

Read the catalog rather than hard-coding a provider list. A client with a baked-in list silently omits every provider added after it shipped, and offers ones that have been retired.

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
)

catalog = client.providers.list()
print(catalog["total"])
for provider in catalog["providers"]:
    print(provider["id"], provider["name"], provider["auth_type"], provider["is_available"])

# Already grouped for a picker, so you do not have to group it yourself.
for category, providers in catalog["by_category"].items():
    print(category, [p["id"] for p in providers])

GET/api/v2/integrations/providers

200 OK

Response field	Meaning
`providers`	Every provider, flat.
`by_category`	The same providers keyed by category, ready to render as sections.
`total`	How many were returned.

Parameter	Contract
`category`	Optional. Narrows to one category.

2. Read one provider's requirements

The detail response carries the authentication method and what the provider can do. Use auth_type to decide whether to render an OAuth button or a credential form.

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
)

provider = client.providers.get("slack")
print(provider["auth_type"], provider["is_available"])
print(provider["capabilities"])

GET/api/v2/integrations/providers/{provider_id}

200 OK

Field	Meaning
`id`, `name`, `description`, `category`	Identity and how to present it.
`auth_type`	How a connection is established. This is the field that decides your UI.
`capabilities`	What the connector supports: `webhooks`, `sync_modes`, `object_types`.
`docs_url`, `icon_url`	Links for your own interface. Both nullable.
`is_available`	Whether it can be connected right now. Check before offering it.

3. Start the authorisation

initiate creates the pending connection and returns the URL to send the user to. Keep the connection_id it gives you — that is what you check afterwards. Redirect the user's browser to the URL; do not fetch it from your server.

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
)

result = client.connections.oauth.initiate(
    "slack",
    redirect_url="https://app.example.com/connections/callback",
)
print(result["authorization_url"])
print(result["state"], result["connection_id"])

POST/api/v2/integrations/oauth/initiate

200 OK

Request field	Contract
`provider_id`	Required. The provider slug. The SDK argument is named `provider`; the wire field is `provider_id`.
`redirect_url`	Optional. Where to send the browser once the handshake finishes.

Response field	Meaning
`authorization_url`	Redirect the browser here.
`state`	Identifies this attempt.
`connection_id`	The pending connection. Store it — this is how you confirm the outcome.

4. Handle the callback

The provider sends the user to MemorySync, which completes the exchange and then redirects the browser to your redirect_uri. Your handler therefore does not exchange a code — it only needs to reflect the outcome in your UI.

Authorisation flow

11. Your server
Calls oauth.initiate and receives an authorization URL and a state value.
22. The browser
You redirect the user to that URL. They approve at the provider.
33. The provider
Calls MemorySync's callback. MemorySync exchanges the code and stores the credential.
44. The browser
MemorySync redirects to your redirect_uri. Your page shows the result.
55. Your server
Calls connections.get on the id from step 1 to confirm before offering configuration.

5. Confirm the handshake completed

Do not treat arriving at your redirect URL as success. A user can abandon the provider screen, deny a scope, or land on your page from a stale tab. Check the connection that initiate returned, and branch on its status.

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
)

connection = client.connections.get(connection_id)
if connection["status"] == "connected":
    pass  # ready to configure
elif connection["status"] == "pending":
    pass  # still at the provider; keep waiting
else:
    print("not connected:", connection["status_message"])

GET/api/v2/integrations/connections/{connection_id}

200 OK

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
)

readiness = client.connections.oauth.status()
print(readiness["configured_count"], "of", readiness["total_count"])
if readiness["providers"].get("slack"):
    pass  # safe to offer the Slack button

GET/api/v2/integrations/oauth/status

200 OK

6. Then configure the source

A connection with status: connected is ready for source-specific setup. OAuth-only providers inherit their readable boundary from source permissions; connectors with explicit selectors expose those operations on their own page.

GitHub

Connect repositories through granted GitHub access.

Notion

Sync pages shared with the Notion integration.

Google Drive

Choose files and folders.

OneDrive

Sync accessible OneDrive and SharePoint files.

Slack

Choose channels and link identities.

Granola

Choose folders and link identities.

Amazon S3

Choose bucket prefixes.

Web Crawler

Validate and import permitted public pages.

Errors and next action

Status	Meaning	Next action
`401`	Missing, malformed or inactive API key.	Check server configuration without printing the key.
`403`	The key lacks `integrations:read` or `integrations:write`.	Grant the scope on the key, or use a key that has it.
`404`	The connection, object or job is not visible to this tenant.	Confirm the identifier belongs to this organization.
`409`	The connection is in a state that forbids the operation.	Read the connection status first and act on it.
`429`	Rate limited, either by MemorySync or by the upstream provider.	Back off; do not tighten a polling loop in response.
`5xx`	Service failure.	Treat a write outcome as uncertain and reconcile by reading the connection back.

Connection Lifecycle

Create without OAuth, update, delete.

Sync & Jobs

Trigger the first sync.

Operations on this page

Authentication and scope

1. Ask what can be connected

2. Read one provider's requirements

3. Start the authorisation

4. Handle the callback

5. Confirm the handshake completed

6. Then configure the source

Errors and next action

Related reference