Managing Identities

Access to PYLON for LinkedIn Engagement Insights is granted through identities you configure in your account. In this guide you'll learn how to create and manage identities.

What are identities?

As a DataSift customer you have a platform account. Using your account login you can access the DataSift dashboard. For platform features except PYLON when you access the API you use your account username and API key (this is your account API key). These are shown when you log into the dashboard.

With PYLON things are different as you are accessing protected data from a service such as LinkedIn on behalf of your end customers. This access requires an access token to be generated, which grants us the permission to access data on your end customers' behalf.

Identities allow you to serve multiple end customers with your one account. For each of your end customers you create an identity with an associated access token. Each identity is assigned its own API key (an identity API key). When you call PYLON API endpoints you use the identity for the end customer your application is serving.

When you begin to serve your customers through your PYLON-based application you will need a separate token for each of your customers. To get started and to explore PYLON you can use your master identity.

tip icon

The platform will maintain the identities that you have set up for your account, but make sure you know which identity relates to which of your end customers. Each identity has a label which you can use to reflect the name or CRM reference id of your end customer.

Working with identities

A good way to understand identities further is by looking at the workflow you'll need to follow when you set up a new customer on your application.

When you have a new customer to onboard for your LinkedIn analytics product you will:

  1. Create a new identity for the customer via the UI or API.
  2. Generate an access token for this new identity.
  3. When making calls to PYLON API endpoints for the new customer you use the identity details that relate to the new customer.

You'll repeat these steps for each customer you onboard to your product.

Viewing existing identities

When your account is set up for PYLON for LinkedIn Engagement Insights it will have one identity already configured. This is the 'master identity' which the dashboard uses for access. You should never use this identity for your end customers. Read more about master identities below.

To view the existing identities in your account, log in to the dashboard, then navigate to Account > Identities.

You can also use the API to view the existing identities in your account by hitting the GET /account/identity endpoint. For example in Python:

from datasift import Client
datasift = Client("your username", "your account API key")
print(datasift.account.identity.list())

You use the Account API endpoints to manage identities. These are not PYLON API endpoints so make sure you use your username and account API key as authorization credentials.

What is the 'master identity'?

If you take a detailed look at the identities for your account you'll see you have one which is flagged as being a master identity. Your account representative will set up your master identity with the LinkedIn access token you provided when you signed up for PYLON.

You can use the master identity to explore new projects, and to test and demo your product. However, when you come to deploy your product for an end customer you need to access the API using an identity that represents the end customer.

You can only have one master identity for your account. If you attempt to create a second you will receive an error.

Creating identities

Using the dashboard

To create a new identity using the dashboard, follow these steps:

  1. Log in to the dashboard.
  2. In the site header, click Account.
  3. On the left-hand side, click Identities.
  4. Click Create an Identity.
  5. In Label, type a name for the identity such as a customer's name. Leave the Master checkbox unchecked.
  6. Click Save.

Your new identity will be created and the details including the identity's API key will be displayed.

Next you need to generate the access token to the identity that represents the customer:

  1. Under Service Tokens, next to LinkedIn, click Generate Token.
  2. Your token has now been generated. Optionally, you can click Verify Token to check the token will work as expected

Using the API

You use the Account API endpoints to manage identities. These are not PYLON API endpoints so make sure you use your username and account API key as authorization credentials.

For example using the Python library:

  1. Import the Python client library and create a client object to call the API.

    from datasift import Client
    datasift = Client("your username", "your account API key")

  2. Call the POST /account/identity endpoint supplying a label for the new identity.

    identity = datasift.account.identity.create('End customer name')

  3. Generate an access token for the identity by using the POST /account/identity/{identity_id}/token endpoint.

    token = datasift.account.identity.token.create(identity['id'], 'linkedin')

tip icon

You may notice the token field has a value of null; this is intentional. Unlike tokens used for PYLON for Facebook Topic Data, DataSift generates these tokens for you. You will have no need to pass us a token string, or access the value of the token being generated.

Updating identities

Once you have created an identity you may need to update the name you have assigned.

Updating an identity name

To update an identity's name using the dashboard:

  1. Navigate to the identities page within your Account settings.
  2. Click on the identity you'd like to edit.
  3. Click Edit this identity.
  4. Update the name and click Save.

Or using the Python client library:

from datasift import Client
datasift = Client("API username", "Account API key")
datasift.account.identity.update(identity['id'], 'Updated identity name')

Calling API endpoints as an identity

To call PYLON API endpoints you need to use credentials for an identity rather than your account API credentials.

Each identity you create is given an API key:

You use your account API username with an identity API key to call API endpoints.

So for example using the Python client:

from datasift import Client
datasift = Client("API username", "Identity API key")
datasift.pylon.list()

Disabling identities

If you need to stop one of your customers accessing your product you can ensure they can no longer access PYLON by disabling any identities you created for them.

You can disable an identity using the PUT /account/identity/{id} endpoint.

For example using the Python client:

from datasift import Client
datasift = Client("API username", "Account API key")
datasift.account.identity.update(identity['id'], status='disabled')

warning icon

It is important that you never disable your master identity. Disabling your master identity invalidates requests from all identities in your account, so effectively disables all of your identities.

Next steps...

Now that you understand more about identities you can think about how to serve your end customers.

You can use your master identity that your account representative will have configured for you for your exploration of PYLON. When you start to serve customers you will need to use an identity for each when accessing the PYLON API.

In the next guide you'll learn how to submit analysis queries:

Analyzing data