Managing Identities

Access to PYLON 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.

dashboard

With PYLON things are different as you are accessing protected data from a service such as Facebook on behalf of your end customers. This access requires an access token granted by the service which gives 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.

Developer-Guide---Managing-Identities

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.

Identities also allow you to allocate your recording allowance and analysis queries allowance across your customers by assigning identity limits.

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.

What are identity limits?

Your package determines two important limits:

  • the daily recording limit for your account.
  • the hourly number of analysis queries for your account.

Within these account limits you're likely to want to serve multiple end customers. Identity limits allow you to portion these account limits across your identities. As identities represent your end customers, effectively you are portioning your account limits across your end customers.

You can set the following limits for each identity using the POST /account/identity/{identity_id}/limit endpoint:

  • total_allowance - the daily volume of interactions the identity can record.
  • analyze_queries - the hourly number calls the identity can make to the pylon/analyze endpoint.

Depending on how you package your product, you might want to make use of identity limits to portion your account limit across each customer. For example, you might:

  • sell packages to your customers based on a daily recording limit, then assign limits that match the package the customer purchases.
  • perform exploratory recordings for each customer you'd like to service, then set limits based upon their use case.

However you decide to assign your overall account limit to your customers we recommend you do assign some limits to your identities, this way you can protect your account and ensure fair usage by your customers.

Note that the sum of the limits you apply can exceed your overall account limit. This is perfectly valid and might be advantageous to you. In effect this introduces competition as your account will still be limited by the overall account limit. Essentially your end customers will be competing to record data before your account limit runs out.

tip icon


You can also use identity limits to explore new audiences or to prototype work for new customers.

Create a new identity and assign the identity a limit. Use this identity to run your exploratory recordings knowing that your exploration will not impact the capacity you need to serve your existing customers.

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 Facebook analytics product you will:

  1. Ask your new customer to register with Facebook for an access token.
  2. Create a new identity for the customer.
  3. Associate the access token with the new identity.
  4. Optionally assign a recording limit to the identity which reflects the package you sold to the customer.
  5. When making calls to PYLON API endpoints for the new customer you use the identity details that relate to the new customer.

Documentation for step 1 of this process can be provided by your account manager. The remaining steps are covered in this article.

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

Viewing existing identities

When your account is set up for PYLON 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.

identity-list

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. This master identity is used when you perform PYLON actions in the dashboard, for example compiling a new filter. Your account representative will set up your master identity with the Facebook 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 and setting limits

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.

identity-details

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

  1. Under Service Tokens, next to Facebook, click Add.
  2. In Token, enter the access token for the customer.
  3. Click Save.

Finally you can optionally assign limits to the identity for a service:

  • Under Service Limits, next to Facebook, click Add.
  • In Total Allowance, enter the number of interactions this identity should be allowed to record.
  • In Analyze Queries, enter the hourly number of analysis queries this identity should be allowed to make.
  • Click Save.

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 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. Assign an access token to the identity by using the POST /account/identity/{identity_id}/token endpoint.

    token = datasift.account.identity.token.create(identity['id'], 'facebook', '<Facebook Token>')

  4. Optionally you can assign recording limits to identities for a service. To assign a limit use the POST /account/identity/{identity_id}/limit endpoint.

    datasift.account.identity.limit.create(identity['id'], 'facebook', <daily recording limit>, <hourly analyze query limit>)

Updating identities and limits

Once you have created an identity you may need to update the name or alter service limits 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')

Removing and updating service limits

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 next to the service limit you'd like to delete or update.
  4. To update the limit, enter the new limit and click Save.
  5. To delete the limit, click Delete.

Or using the Python client library:

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

# Updates identity limits
datasift.account.identity.limit.update(identity['id'], 'facebook', <daily recording limit>, <hourly analyze query limit>)

# Deletes identity limits
datasift.account.identity.limit.delete(identity['id'], 'facebook')

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:

identity_1

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.

For more information on Facebook access tokens and how these are used by the platform take a look at the FAQ page.

Next take a look at the Recording Data guide.