curl --request GET \
--url https://operator.opus.com/api/v1/integration/connect/{CONNECTION_TOKEN} \
--header 'x-service-key: {YOUR_SERVICE_KEY}'
import time
import requests
token = "{CONNECTION_TOKEN}"
url = f"https://operator.opus.com/api/v1/integration/connect/{token}"
headers = {"x-service-key": "{YOUR_SERVICE_KEY}"}
# The window is 10 minutes; give up rather than poll forever.
deadline = time.time() + 600
while time.time() < deadline:
status = requests.get(url, headers=headers).json()
if status["status"] != "pending":
break
time.sleep(5)
print(status)
const token = "{CONNECTION_TOKEN}";
const url = `https://operator.opus.com/api/v1/integration/connect/${token}`;
const headers = { "x-service-key": "{YOUR_SERVICE_KEY}" };
// The window is 10 minutes; give up rather than poll forever.
const deadline = Date.now() + 600_000;
let status;
while (Date.now() < deadline) {
status = await (await fetch(url, { headers })).json();
if (status.status !== "pending") break;
await new Promise((resolve) => setTimeout(resolve, 5000));
}
console.log(status);
{
"status": "succeeded",
"activeIntegrationId": "{ACTIVE_INTEGRATION_ID}",
"activeIntegrationVersionId": "{ACTIVE_INTEGRATION_VERSION_ID}",
"activeCredentialId": "{ACTIVE_CREDENTIAL_ID}",
"workspaceId": "{WORKSPACE_ID}",
"testPassed": null,
"testError": null
}
{
"status": "pending",
"activeIntegrationId": null,
"activeIntegrationVersionId": null,
"activeCredentialId": null,
"workspaceId": "{WORKSPACE_ID}",
"testPassed": null,
"testError": null
}
Integrations
Check a Connection
Read the outcome of a connection that needed authorizing
GET
/
api
/
v1
/
integration
/
connect
/
{connectionToken}
curl --request GET \
--url https://operator.opus.com/api/v1/integration/connect/{CONNECTION_TOKEN} \
--header 'x-service-key: {YOUR_SERVICE_KEY}'
import time
import requests
token = "{CONNECTION_TOKEN}"
url = f"https://operator.opus.com/api/v1/integration/connect/{token}"
headers = {"x-service-key": "{YOUR_SERVICE_KEY}"}
# The window is 10 minutes; give up rather than poll forever.
deadline = time.time() + 600
while time.time() < deadline:
status = requests.get(url, headers=headers).json()
if status["status"] != "pending":
break
time.sleep(5)
print(status)
const token = "{CONNECTION_TOKEN}";
const url = `https://operator.opus.com/api/v1/integration/connect/${token}`;
const headers = { "x-service-key": "{YOUR_SERVICE_KEY}" };
// The window is 10 minutes; give up rather than poll forever.
const deadline = Date.now() + 600_000;
let status;
while (Date.now() < deadline) {
status = await (await fetch(url, { headers })).json();
if (status.status !== "pending") break;
await new Promise((resolve) => setTimeout(resolve, 5000));
}
console.log(status);
{
"status": "succeeded",
"activeIntegrationId": "{ACTIVE_INTEGRATION_ID}",
"activeIntegrationVersionId": "{ACTIVE_INTEGRATION_VERSION_ID}",
"activeCredentialId": "{ACTIVE_CREDENTIAL_ID}",
"workspaceId": "{WORKSPACE_ID}",
"testPassed": null,
"testError": null
}
{
"status": "pending",
"activeIntegrationId": null,
"activeIntegrationVersionId": null,
"activeCredentialId": null,
"workspaceId": "{WORKSPACE_ID}",
"testPassed": null,
"testError": null
}
Report what happened to an OAuth connection after Connect an Integration returned
pending_authorization.
An OAuth flow finishes in a browser, not in your call: a person opens the authorizationUrl, authorizes with the provider, and is returned to Opus. Your request is long gone by then. This endpoint is how you learn whether it worked and which connection resulted.
Requires the Integration: Read permission in at least one workspace. The connection is matched against the workspaces you hold it in, so a token from a workspace you cannot read is reported as expired.
Only needed for OAuth. A non-OAuth connect returns its ids immediately and there is nothing to poll.
Headers
string
required
Your API authentication key
Path Parameters
string
required
The
connectionToken returned by Connect an Integration.Statuses
status
The authorization window is still open. Nobody has finished authorizing yet.
status
Someone authorized and the connection exists. The ids are on the response.
status
Authorization was attempted and did not complete — a denied consent screen, or a token exchange the provider rejected.
status
The window closed without a callback, the token is not one of yours, or there is no such token at all. Start again with a fresh connect.
The authorization window is 10 minutes from the connect call. A person who takes longer — or who has to create an account with the provider first — will find the link dead, and this endpoint reports
expired. Connect again to get a fresh authorizationUrl.Response
string
required
One of
pending, succeeded, failed or expired. Every field below is always present on the response; they are null until a connection exists.string
The connection — this is what a workflow refers to. Present once the status is
succeeded.string
The connection’s current version.
string
The stored credential.
string
The workspace the connection lives in.
boolean
Whether the smoke test succeeded.
null when no testActionVersionId was sent to connect, because nothing was tested.string
Why it failed, when it did.
Errors
Unauthorized
Missing, invalid, or expired API key.
Forbidden
The key owner lacks the Integration: Read permission.
There is deliberately no
404. A token that belongs to someone else, and a token that was never issued, both come back as expired — the same answer as one of yours that timed out. If an unknown token answered differently, this endpoint could be used to discover whether someone else’s connection exists.The practical consequence: expired does not confirm you sent a real token. Check for a typo before assuming the window closed.curl --request GET \
--url https://operator.opus.com/api/v1/integration/connect/{CONNECTION_TOKEN} \
--header 'x-service-key: {YOUR_SERVICE_KEY}'
import time
import requests
token = "{CONNECTION_TOKEN}"
url = f"https://operator.opus.com/api/v1/integration/connect/{token}"
headers = {"x-service-key": "{YOUR_SERVICE_KEY}"}
# The window is 10 minutes; give up rather than poll forever.
deadline = time.time() + 600
while time.time() < deadline:
status = requests.get(url, headers=headers).json()
if status["status"] != "pending":
break
time.sleep(5)
print(status)
const token = "{CONNECTION_TOKEN}";
const url = `https://operator.opus.com/api/v1/integration/connect/${token}`;
const headers = { "x-service-key": "{YOUR_SERVICE_KEY}" };
// The window is 10 minutes; give up rather than poll forever.
const deadline = Date.now() + 600_000;
let status;
while (Date.now() < deadline) {
status = await (await fetch(url, { headers })).json();
if (status.status !== "pending") break;
await new Promise((resolve) => setTimeout(resolve, 5000));
}
console.log(status);
{
"status": "succeeded",
"activeIntegrationId": "{ACTIVE_INTEGRATION_ID}",
"activeIntegrationVersionId": "{ACTIVE_INTEGRATION_VERSION_ID}",
"activeCredentialId": "{ACTIVE_CREDENTIAL_ID}",
"workspaceId": "{WORKSPACE_ID}",
"testPassed": null,
"testError": null
}
{
"status": "pending",
"activeIntegrationId": null,
"activeIntegrationVersionId": null,
"activeCredentialId": null,
"workspaceId": "{WORKSPACE_ID}",
"testPassed": null,
"testError": null
}
Was this page helpful?