Manage data source login links

Data source login links are anonymous URLs, that you can use to request data source authentications to your team.

• List login links
• Get login link
• Add login link
• Update login link
• Close login link
• Link status codes
• Custom redirect URLs
• Restrictions
• Errors

List login links

Response

HTTP 200 OK
{
    "meta": {
        "request_id": "WnjTGeKqOXTnkZQMbZCfVMdmswv2wAzx"
    },
    "data": [
        {
            "link_id": "dsll_1",
            "status_code": "OPEN",
            "description": "My link",
            "ds_id": "AC",
            "ds_name": "Microsoft Advertising (Bing)",
            "require_username": "",
            "user_id": "usr_1",
            "user_email": "info@supermetrics.com",
            "login_url": "https://api.supermetrics.com/v2/datasource/login/renew/0qglMN....",
            "created_time": "2021-10-22T11:47:16+00:00",
            "expiry_time": "2021-10-12T23:59:00+00:00"
        }
    ]
}

Permissions

ds_login_links_read

Get login link

• link_id string
  Supermetrics login link ID

Response

HTTP 200 OK
{
    "meta": {
        "request_id": "WnjTGeKqOXTnkZQMbZCfVMdmswv2wAzx"
    },
    "data": {
        "link_id": "dsll_1",
        "status_code": "CLOSED",
        "description": "My link",
        "ds_id": "AC",
        "ds_name": "Microsoft Advertising (Bing)",
        "require_username": "",
        "redirect_url": "",
        "redirect_verifier": "",
        "user_id": "usr_1",
        "user_email": "info@supermetrics.com",
        "login_url": "https://api.supermetrics.com/v2/datasource/login/renew/0qglMN....",
        "created_time": "2021-10-22T11:47:16+00:00",
        "expiry_time": "2021-10-12T23:59:00+00:00",
        "login_id": "dsl_8",
        "login_time": "2021-10-22T12:15:16+00:00",
        "login_username": "info@supermetrics.com"
    }
}

Errors

LINK_NOT_FOUND

Permissions

ds_login_links_read

Add login link

• ds_id string
  Required. Data source ID. See data sources for more.
• expiry_time string
  Required. Link expiry time as date, datetime or relative time string. Value is saved as ISO 8601, defaulting to midnight as time of day.
• description string
  Optional. Internal description for the link. Not shown during the authentication attempt.
• require_username string
  Optional. Data source username that needs to be used in authentication attempt. Normally used when renewing existing credentials.
• redirect_url string
  Optional. Custom URL to redirect to after successful authentication. See custom redirect URLs for more.

Request

POST https://api.supermetrics.com/enterprise/v2/ds/login/link
Authorization: Bearer <your api key>
Content-Type: application/json

{
    "ds_id": "GAWA",
    "description": "My test link",
    "expiry_time": "24 hours"
}

Response

Errors

LINK_LIMIT_EXCEEDED

Permissions

ds_login_links_write

Update login link

You can only update link details that do not affect any ongoing authentication attempts.

• link_id string
  Supermetrics login link ID
• description string
  Optional. Internal description for the link. Not shown during the authentication attempt.

Response

Errors

LINK_NOT_FOUND, LINK_UPDATE_FAILED

Permissions

ds_login_links_write

Close login link

Login link will be stop accepting new requests once it's closed, but closing will not affect already started authentication attempts.

• link_id string
  Supermetrics login link ID

Response

Errors

LINK_NOT_FOUND, LINK_UPDATE_FAILED

Permissions

ds_login_links_write

Link status codes

Custom redirect URLs

For system integrations, user can be redirected back to a custom URL after successful authentication. This URL must always use HTTPS, and it supports custom URL parameters.

Returned parameters

To identify which data source login link was used in the authentication, the following parameters are always appended to redirect URL.

https://localhost/my/callback?
  &my_state=my_value
  &link_id=dsll_1
  &link_verifier=weKWvugnbCmKnuAayBUSAqsmceOCscfzyJ_IWcVa4Vt

Please note that we highly recommend using additional state parameters in your integration to further protect against request forgery attacks

Restrictions

• Note that you are, by default, limited to maximum of 5 links in OPEN state at any given time. Please contact us or your Supermetrics sales representative to increase this number.

• Links older than 90 days are automatically removed from the system, regardless what state they are in.

• All authenticated login credentials need a valid Supermetrics user ID as the primary owner and contact user. This is resolved from the authentication method used to call the endpoint. Shared API keys identify as the first user in the team with either OWNER or ADMIN role.

Errors