Create a Looker API Key

What is an API key?

An API key is a set of credentials belonging to a user in your Looker instance. Spectacles can use an API key to log in to your Looker instance via the Looker API. From there, Spectacles can run queries and tests.

We'll create a dedicated Looker user with its own role and permissions, then create an API key for that user that we'll provide to Spectacles to run tests.

Create a Spectacles permission set and role

Before we create a Looker user for Spectacles, let's create a permission set for that user that allows Spectacles to do everything it needs to do. This will also ensure that Spectacles follows least privilege and only receives the necessary permissions needed to function.

1. In Looker, go to Admin > Roles. Click "New Permission Set".

2. Name the Permission Set "Spectacles User" and check the boxes for the following permissions:

   • access_data - allows Spectacles to run and see the results of queries.
   • see_lookml_dashboards - allows Spectacles to see Content Validator errors for LookML dashboard tiles
   • see_looks - required to grant the following permissions:
     • see_user_dashboards - allows Spectacles to see Content Validator errors for user-defined dashboard tiles
     • develop - allows Spectacles to enter development mode.
     • see_lookml - allows Spectacles to read LookML.
     • see_sql - allows Spectacles to show you SQL for failed queries.

3. Create the permission set.

We'll also create a role for our Spectacles user so we can easily assign the necessary permissions.

1. Click "New Role".
2. Name the role "Spectacles User" as well.
3. Select the "Spectacles User" permission set and the right model set (depending on which models you want Spectacles to be able to test).
4. Create the role.

We'll assign this role to our dedicated user in the next step.

Create a dedicated Spectacles Looker user

We strongly recommend creating a dedicated Spectacles user in Looker to ensure a human user doesn't accidentally change the Git branch or turn off development mode in the middle of a validation.

1. In Looker, go to Admin > Users.
2. Click Add Users. Provide any email you want.
3. Under Roles, check "Spectacles User".
4. Click Done.

Create an API key for the user

1. Find the user you just created and click Edit
2. You can give this user a name like Spectacles Worker.
3. Under API3 Keys, click Edit Keys.
4. Generate a new API key by clicking New API Key.
5. Copy down the client ID and client secret.

These are the credentials that Spectacles will use to authenticate as your dedicated Looker user and run tests. Once you have a client ID and client secret, you're ready to set up Spectacles.

warning

If you're creating a pool of Looker users for concurrent runs, make sure you create a unique Looker user for each Spectacles worker. You should never give two Spectacles workers API keys for the same Looker user, even if the API keys are different from each other.

For detailed instructions on how to set this up correctly, read the guide Add Spectacles Workers.