API Authentication and Keys

Who is calling: email and API key

Every API call says who you are with two values: email, the email of your Opensolr account, and api_key. Send them as normal GET or POST parameters, or in a JSON body with the same names.

Two kinds of keys

• The master API key: one per account. It can do everything the API can: create and delete indexes, change configuration files and passwords, spend your AI allowance. It is also the first password of every new index.
• Scoped keys: as many as you like. Each one works only for the endpoints you tick and, if you want, only on the indexes you pick, until a date you choose. Anything else answers 403.

Give a site, a script or a colleague a scoped key whenever they do not need everything.

Find your master key

Open Account › API Keys. Under Master API key, click Reveal or Copy. Your account dashboard shows it too, as Master REST API Key.

To replace it, click Generate A New API Key on your account dashboard, then update your apps. The passwords of your existing indexes do not change. What changes when you do it. To stop handing the master key to apps at all: switch to scoped keys.

Create a scoped key

1. Open Account › API Keys and click + Create a scoped key.
2. Name this key, so you know later what it is for.
3. What may this key do? Tick the endpoints it needs. The filter and select all help. For an Opensolr module, one box ticks them all: Drupal Opensolr Search, Drupal Search API Opensolr, WordPress.
4. Which indexes may it touch? Pick All of my indexes, tick some, or match index names by pattern: * stands for any characters and ? for one, so sandbox_* covers every index whose name starts with sandbox_.
5. Set an Expiry date (optional).
6. Click Create key and copy it.

Each key in Your scoped keys has Edit, Revoke (and Enable again), Regenerate and Delete. A scoped key used outside its scope answers 403 ERROR_SCOPED_KEY_ENDPOINT_NOT_ALLOWED or 403 ERROR_SCOPED_KEY_CORE_NOT_ALLOWED. The full guide: Master API Key vs Scoped API Keys.

Four endpoints also need a signature

These calls add a signature parameter: a hex HMAC-SHA256, keyed with your API key.

• get_account_summary and get_settings_dashboard sign core_name followed by email.
• add_crawl_url_signed and delete_crawler_url sign url followed by core_name.

signature = hex( HMAC-SHA256( key: api_key, message: core_name + email ) )

A wrong signature answers ERROR_INVALID_SIGNATURE.