Endpoints
GET /status
Checks the status of the connector. This endpoint is mainly used for successfully creating the app in Opal and verifying that the connector is properly configured.
Query params
| param | type | description |
|---|---|---|
| app_id | string | The Opal app ID to list resources for. This allows your service to distinguish apps if it’s supporting multiple apps via the same set of endpoints |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
GET /resources
Returns a list of all resources for the app in question. This endpoint is called after you’ve imported resources to the app, so you may not see it being called when you first create your app.
To distinguish resources pulled from multiple sources, you can include the type in the identifier, then base64-encode the ID so it can be properly parsed—e.g., base64(resource-type:1).
Query params
| param | type | description |
|---|---|---|
| app_id | string | The Opal app ID to list resources for. This allows your service to distinguish apps if it’s supporting multiple apps via the same set of endpoints. |
| cursor | string | For pagination. Empty string on the first call, then set to the value provided via next_cursor. |
| parent_id | string | Optional: Used for nested resources. If you enable Nested Resources in the Opal connector form, this endpoint finds the resource specified by parent_id and returns its immediate children. See Create your own connector for more information. |
| param | type | description |
|---|---|---|
| resources | array of objects | List of the resource objects. See below for what each resource should include. |
| next_cursor | string | The cursor that should be used for the next call. If cursor is an empty string, it is assumed that all resources have been fetched. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
| field | type | description |
|---|---|---|
| id | string | The id of the resource that uniquely identifies it in your system. It can be at most 65535 characters. |
| name | string | The name of the resource. |
| description | string | The description of the resource. |
GET /resources/{resource_id}
Get a specific resource by its ID.
Path params
| param | type | description |
|---|---|---|
| resource_id | string | The id of the resource. |
| param | type | description |
|---|---|---|
| app_id | string | The Opal app ID to list resources for. This allows your service to distinguish apps if it’s supporting multiple apps via the same set of endpoints. |
| field | type | description |
|---|---|---|
| resource | object | Resource object |
| field | type | description |
|---|---|---|
| id | string | The id of the resource that uniquely identifies it in your system. It should match the ID (<resource_id>) of the request. |
| name | string | The name of the resource. |
| description | string | The description of the resource. |
| can_have_usage_data | boolean | Optional. This property is used to enable ingesting usage events for a resource to enable LPPM for custom connections. See the events endpoint for more information. false if unspecified. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
GET /resources/{resource_id}/access_levels
If your resource doesn’t require any access level, this endpoint can return
"access_levels": [].| param | type | description |
|---|---|---|
| resource_id | string | The id of the resource to retrieve the access levels of. |
| param | type | description |
|---|---|---|
| app_id | string | The Opal app ID to list resources for. This allows your service to distinguish apps if it’s supporting multiple apps via the same set of endpoints |
| cursor | string | For pagination. Empty string on the first call, then set to the value provided via next_cursor |
| param | type | description |
|---|---|---|
| access_levels | array of objects | List of the access levels objects. See below for what each object should include. If your resource doesn’t require any access level, it can return []. |
| next_cursor | string | The cursor that should be used for the next call. If cursor is an empty string, it is assumed that all resources have been fetched. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
| field | type | description |
|---|---|---|
| id | string | ID of the access level to grant to this user. |
| name | string | The user-facing name of the access level. |
GET /resources/{resource_id}/users
Returns the users that currently have access to the provided resource.
Path params
| param | type | description |
|---|---|---|
| resource_id | string | The id of the resource you’re trying to list the details of, as returned as id in the /resources/<resource_id> endpoint. |
| param | type | description |
|---|---|---|
| app_id | string | The app id specified by the end user during connection process. This can be used in your end system to distinguish apps if you are supporting multiple apps via the same set of endpoints |
| cursor | string | For pagination. Empty string on the first call, then passed values provided via next_cursor |
| param | type | description |
|---|---|---|
| users | array of objects | List of the resource user objects. See below for what each resource should include |
| next_cursor | string | The cursor that should be used for the next call. If cursor is an empty string, it is assumed that all resources have been fetched. |
| param | type | description |
|---|---|---|
| message | string | An error message to expose in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
| field | type | description |
|---|---|---|
| user_id | string | The user identifier used in the remote system, this will be provided back to you when making access changes. |
| string | The email of the user. This will be used on our end to correlate it with Opal users. Although not required at the moment, we’d like implementers to include this value as well. | |
| access_level | object | The access level granted to the user. If omitted, the default access level remote ID value (empty string) is used. |
POST /resources/{resource_id}/users
Adds a user to the access list of the specified resource.
Path params
| param | type | description |
|---|---|---|
| resource_id | string | The id of the resource you’re trying to add the user to |
| param | type | description |
|---|---|---|
| app_id | string | The app id specified by the end user during connection process. This can be used in your end system to distinguish apps if you are supporting multiple apps via the same set of endpoints |
| user_id | string | The id of the user to add to the resource |
| access_level_id | string (optional) | The ID of the access level to assign to the user. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
DELETE /resources/{resource_id}/users/{user_id}
Remove a user from the access list of the specified resource.
Path params
| param | type | description |
|---|---|---|
| resource_id | string | The id of the resource to be edited. |
| user_id | string | The id of the user to be removed. |
| param | type | description |
|---|---|---|
| app_id | string | The app id specified by the end user during connection process. This can be used in your end system to distinguish apps if you are supporting multiple apps via the same set of endpoints |
| access_level_id | string (optional) | The ID of the access level associated to the user for this resource. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
GET /groups
Returns a list of all groups for the app in question. The /groups endpoints are only called if Connector Groups is enabled in the custom app form.
Query params
| param | type | description |
|---|---|---|
| app_id | string | The Opal app ID to list groups for. This allows your service to distinguish apps if it’s supporting multiple apps via the same set of endpoints |
| cursor | string | For pagination. Empty string on the first call, then set to the value provided via next_cursor |
| param | type | description |
|---|---|---|
| groups | array of objects | List of the group objects. See below for what each group should include |
| next_cursor | string | The cursor that should be used for the next call. If cursor is an empty string, it is assumed that all groups have been fetched. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
| field | type | description |
|---|---|---|
| id | string | The id of the group that uniquely identifies it in your system. |
| name | string | The name of the group |
| description | string | The description of the group |
GET /groups/{group_id}
Get a specific group by its id.
Path params
| param | type | description |
|---|---|---|
| group_id | string | The id of the resource |
| param | type | description |
|---|---|---|
| app_id | string | The Opal app ID to list resources for. This allows your service to distinguish apps if it’s supporting multiple apps via the same set of endpoints |
| field | type | description |
|---|---|---|
| group | object | A Group object. |
| field | type | description |
|---|---|---|
| id | string | The id of the resource that uniquely identifies it in your system. |
| name | string | The name of the resource |
| description | string | The description of the resource |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
GET /groups/{group_id}/users
Returns the users that currently belong to the provided group.
Path params
| param | type | description |
|---|---|---|
| group_id | string | The id of the group you’re trying to list the details of |
| param | type | description |
|---|---|---|
| app_id | string | The app id specified by the end user during connection process. This can be used in your end system to distinguish apps if you are supporting multiple apps via the same set of endpoints |
| cursor | string | For pagination. Empty string on the first call, then passed values provided via next_cursor |
| param | type | description |
|---|---|---|
| users | array of objects | List of the group user objects. See below for what each group should include |
| next_cursor | string | The cursor that should be used for the next call. If cursor is an empty string, it is assumed that all resources have been fetched. |
| param | type | description |
|---|---|---|
| message | string | An error message to expose in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
| field | type | description |
|---|---|---|
| user_id | string | The user identifier used in the remote system, this will be provided back to you when making access changes. |
| string | The email of the user. This will be used on our end to correlate it with Opal users. Although not required at the moment, we’d like implementers to include this value as well. |
POST /groups/{group_id}/users
Adds a user to the access list of the specified group.
Path params
| param | type | description |
|---|---|---|
| group_id | string | The id of the group you’re trying to add the user to |
| param | type | description |
|---|---|---|
| app_id | string | The app id specified by the end user during connection process. This can be used in your end system to distinguish apps if you are supporting multiple apps via the same set of endpoints |
| user_id | string | The id of the user to add to the group |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
DELETE /groups/{group_id}/users/{user_id}
Remove a user from the access list of the specified group.
Path params
| param | type | description |
|---|---|---|
| group_id | string | The id of the group to be edited. |
| user_id | string | The id of the user to be removed. |
| param | type | description |
|---|---|---|
| app_id | string | The app id specified by the end user during connection process. This can be used in your end system to distinguish apps if you are supporting multiple apps via the same set of endpoints |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
GET /groups/{group_id}/resources
Returns the resources that currently belong to the provided group.
Path params
| param | type | description |
|---|---|---|
| group_id | string | The id of the group you’re trying to list the details of |
| param | type | description |
|---|---|---|
| app_id | string | The app id specified by the end user during connection process. This can be used in your end system to distinguish apps if you are supporting multiple apps via the same set of endpoints |
| cursor | string | For pagination. Empty string on the first call, then passed values provided via next_cursor |
| param | type | description |
|---|---|---|
| resources | array of objects | List of the group resource objects. See below for what each group should include |
| next_cursor | string | The cursor that should be used for the next call. If cursor is an empty string, it is assumed that all resources have been fetched. |
| param | type | description |
|---|---|---|
| message | string | An error message to expose in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
| field | type | description |
|---|---|---|
| resource_id | string | The resource identifier used in the remote system, this will be provided back to you when making access changes. |
| access_level | object | The access level the group has access to the resource with. |
POST /groups/{group_id}/resources
Adds a resource to the access list of the specified group.
Path params
| param | type | description |
|---|---|---|
| group_id | string | The id of the group you’re trying to add the resource to |
| param | type | description |
|---|---|---|
| app_id | string | The app id specified by the end user during connection process. This can be used in your end system to distinguish apps if you are supporting multiple apps via the same set of endpoints |
| resource_id | string | The id of the resource to add to the group |
| access_level_id | string (optional) | The ID of the access level to assign to the group to the resource. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
DELETE /groups/{group_id}/resources/{resource_id}
Remove a resource from the access list of the specified group.
Path params
| param | type | description |
|---|---|---|
| group_id | string | The id of the group to be edited. |
| resource_id | string | The id of the resource to be removed. |
| param | type | description |
|---|---|---|
| app_id | string | The app id specified by the end user during connection process. This can be used in your end system to distinguish apps if you are supporting multiple apps via the same set of endpoints |
| access_level_id | string (optional) | The ID of the access level associated to the group for this resource. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
GET /groups/{group_id}/member-groups
Returns member groups for the specified group. Required if you enable Nested Groups when you create the custom app.
Path params
| param | type | description |
|---|---|---|
| group_id | string | The ID of the parent group. |
| param | type | description |
|---|---|---|
| app_id | string | The Opal app ID to list users for. This allows your service to distinguish apps if it’s supporting multiple apps via the same set of endpoints |
| cursor | string | For pagination. Empty string on the first call, then set to the value provided via next_cursor |
| param | type | description |
|---|---|---|
| groups | array of objects | List of the member groups. See the following Member group object for fields. |
| next_cursor | string | The cursor that should be used for the next call. If cursor is an empty string, it is assumed that all resources have been fetched. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
| field | type | description |
|---|---|---|
| group_id | string | The id of the member group that uniquely identifies it in your system. |
| name | string | The name of the group. |
| description | string | The description of the group. |
POST /groups/{group_id}/member-groups
Add a member group to the specified group. Required if you enable Nested Groups when you create the custom app.
Path params
| param | type | description |
|---|---|---|
| group_id | string | The ID of the parent group. |
| param | type | description |
|---|---|---|
| group_id | string | The ID of the member group to add. |
| app_id | string | The ID of the custom app. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
GET /users
Returns a list of users for your custom connector app.
Query params
| param | type | description |
|---|---|---|
| app_id | string | The Opal app ID to list users for. This allows your service to distinguish apps if it’s supporting multiple apps via the same set of endpoints |
| cursor | string | For pagination. Empty string on the first call, then set to the value provided via next_cursor |
| param | type | description |
|---|---|---|
| users | array of objects | List of the user objects. See below for what each user should include |
| next_cursor | string | The cursor that should be used for the next call. If cursor is an empty string, it is assumed that all resources have been fetched. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
| field | type | description |
|---|---|---|
| id | string | The id of the user that uniquely identifies it in your system. |
| string | The email of the user, this is required to associate the user in Opal. |
POST /users
This endpoint enables users to be provisioned into a custom connector app. This functionality is only available if user provisioning has been enabled for the connection.
Body params (JSON encoded)
| field | type | description |
|---|---|---|
| user_id | string | The Opal User ID being created in your end system |
| attributes | UserAttributes | The attributes of the user to create in your custom connector app. |
| manager | UserAttributes | The attributes of the manager of the user |
| user_tags | Array | The tags of the user that were ingested by Opal |
| field | type | description |
|---|---|---|
| string | The email of the user | |
| first_name | string | The first name of the user |
| last_name | string | The last name of the user |
| title | string | The title of the user, if available |
| team | string | The team the user is a part of, if available |
| profile_url | string | A URL to the user’s profile photo |
| secondary_emails | Array | The secondary emails of the user, if available |
| field | type | description |
|---|---|---|
| key | string | The key of the tag in Opal |
| value | string | The value of the tag in Opal |
| tag_id | string | The Opal ID of the tag |
| connection_id | string | The Opal ID of the connection where this tag was sourced from |
| param | type | description |
|---|---|---|
| remote_user_id | string | The ID of the user in the custom connector app. This must be returned by your implementation and will be used by Opal to refer to this user in the future. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
DELETE /users/{user_id}
This endpoint deprovisions user accounts in a custom connector application. This functionality is only available if user deprovisioning has been enabled for the connection.
Path params
| param | type | description |
|---|---|---|
| user_id | string | The ID of the user to be removed from the application. |
| param | type | description |
|---|---|---|
| app_id | string | The app ID specified by the end user during connection process. This can be used in your end system to distinguish apps if you are supporting multiple apps via the same set of endpoints. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
GET /events
This endpoint is only called if Connector Event Ingestion is enabled in the custom app form.
Query params
| param | type | description |
|---|---|---|
| app_id | string | Required. The Opal app ID to list events for. This allows your service to distinguish apps if it’s supporting multiple apps via the same set of endpoints |
| cursor | string | For pagination. Empty string on the first call, then set to the value provided via next_cursor |
| start | string | Return events starting from this date. Use the format YYYY-MM-DDT00:00:00Z. |
| end | string | Return events ending before this date. Use the format YYYY-MM-DDT00:00:00Z. |
| param | type | description |
|---|---|---|
| events | array of objects | List of the event objects. See below for what each event should include |
| next_cursor | string | The cursor that should be used for the next call. If cursor is an empty string, it is assumed that all evets have been fetched. |
| param | type | description |
|---|---|---|
| message | string | An error message that will be exposed in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
| field | type | description |
|---|---|---|
| event_id | string | The id of the event that uniquely identifies it in your system. |
| event_type | OneOf: login.success | The type of the event. |
| occurred_at | RFC3339 datetime string | The date and time at which the event occurred. Return as a string using the following format: {year}-{month}-{day}T{hour}:{minute}:{second}.{microsecond}%z. |
| actor_user_identifier | ActorUserIdentifier object | An ActorUserIdentifier object uniquely identifying the user that performed this event. See below for what this object should include. |
| event_content | OneOf: EventContentLoginSuccess object | The content of this event, which is specific to the event type. See below for what each event content should include. |
| field | type | description |
|---|---|---|
| user_id | string | The id of the user that uniquely identifies it in your system. |
| user_email | string | The email of the user, this is required to associate the user in Opal. |
| field | type | description |
|---|---|---|
| resource_id | string | The id of the resource that the user logged in to. |
Error codes
All error codes need to implement the following object:| param | type | description |
|---|---|---|
| message | string | An error message to expose in the Opal UI. |
| code | integer | The error code that describes the error. See Error Codes for details. |
| Status code | Meaning |
|---|---|
| 200 | Response successful. |
| 401 | Invalid request signature error. |
| 404 | Entity not found (eg. resource, user, access level). |
| 500 | Unexpected error. |
Signature
To ensure that the API calls originate from Opal, we provide a header in each request that represents the encrypted request payload with a secret that is generated when creating the app connector in Opal. See Setup connector app in Opal for more details. On each HTTP request that Opal sends, we add anX-Opal-Signature HTTP header. The signature is created by combining the signing secret with the body of the request we’re sending using a standard HMAC-SHA256 keyed hash.
Here is an example with Node to compute the signature using your signing secret. You may compare it against the value retrieved from the X-Opal-Signature header:
{}. See the link below for more examples.
Check Create your own connector for signature examples.
