Service accounts

Service accounts are administrative accounts specifically meant for API integrations. A service account is one of your organization’s administrators, but it is not tied to a specific person. In your API integration, you use a service account to perform the API calls. It is not possible to log in to a service account, as you can do with your regular account.

💡 Why can't I use a regular account for my API integration?

It is still possible to use a regular, personal account for an API integration. However, this means that all actions taken by this integration are effectively done by the person that is linked to this account. Using a service account is more transparent, because it clearly indicates that actions are being taken by a machine rather than a person.

There are several distinct benefits to using a service account for an API integration compared to using the credentials of a human administrator:

• Continuity – API integrations are no longer reliant on a specific person, meaning that if an administrator leaves the organization, there is no impact on the technical connections.
• Auditability – Actions performed by a service account are logged as such. No actions are taken by a human administrator without the user present.
• Access control – The permissions and access available to the service account can be set to the minimum required levels.
• Robustness – There are no interactive steps involved in obtaining a new access token, which is more suitable for an automated integration.

Setting up a service account

In order to set up a service account, you must be an administrator of your organization. In addition, you must also have the “Manage service accounts” permission. Please contact Drillster support if you require this permission.

To set up a new service account, navigate to the “Accounts” section in the Drillster user console, and click the “plus” icon.

Next, select “Add service account…”. A service account only has a name — please choose something that is meaningful in the context of your organization. The account name may be shown to other users in various screens.

In the various user interfaces, service accounts are displayed with a small wrench icon badge attached to the avatar image to distinguish them from human administrators.

Assigning access and permissions

For all practical purposes, a service account is an administrator in your organization, just like any human administrators. This means that in order for a service account to be able to do anything meaningful in the organization (through API requests), the account must first be given the appropriate permissions and access.

After setting up a new service account, the account must be set up with the appropriate permissions, just like you would for any newly created human administrator. This is done by selecting the service account from the list of managed accounts. This will open the detail page of that service account, with the “Permissions” tab shown. Assign the appropriate permissions for the service account.

In many scenarios, service accounts will be used for group management. Service accounts do not have access to any groups by default – just like any other administrator group management access needs to be granted first. A service account may be set up as a group manager or viewer for specific groups, but it is also possible to make the service account a “Groups administrator”, meaning that the account becomes a manager or viewer of all groups in the organization.

Generating a key pair

To perform API calls, you first need to obtain an OAuth 2.0 access token, using your service account. The access token is obtained by using a JWT Authorization Grant. This is an extension of OAuth 2.0, and is defined in JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants (RFC-7523 2.1).

The JWT Authorization Grant requires an RSA key pair for your service account. The key pair is generated by the Drillster platform, and consist of a public key and a private key. Drillster only retains the public key. The private key is given to the administrator setting up the service account. It is the responsibility of the administrator to save the private key.

⚠️ Private keys are secret!

Your service account's private key must be kept secret at all times. This means that it must never be used in what are considered by OAuth as public client applications:

• Native desktop or mobile applications
• JavaScript-based client-side applications (anything running in a browser)

The part of your Drillster integration that uses this private key must not be implemented in such applications — only in server-based applications.

In order to generate a key pair, go to the account detail screen in the Drillster console for the desired service account. Navigate to the “Keys” tab. Next, click the “plus” button and select “Generate new key” to create a new key pair.

This should result in the generation of a new key pair. The public key is stored in the Drillster system, and the private key is shown to the user. The private key is not stored anywhere on Drillster's systems. If desired it is also possible to supply your own public key. Please contact Drillster support for details.

Keep in mind that this your only chance to view and download the private key. Please click on “Download JSON key file”. This should download the private key to your computer, wrapped in a small JSON file. You can also copy the private key itself, without metadata, to the clipboard by clicking the “copy” link. Please ensure that you have the key file in your possession before dismissing the popup.

The private key can be viewed of as the password for the service account. It is your responsibility to keep it secret and to keep it secure. Should the private key ever become compromised, be sure to delete the associated public key from the Drillster system by clicking the appropriate delete icon in the list of keys. Once the public key has been removed, the private key can no longer be used.

The downloaded JSON key file looks something like this:

{
  "keyId":"cf9f895ff1f64e2f9ceea45074f56c52",
  "privateKey":"-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAxIBAQCQbJx3YdmaXAtJ\nOvPHEZ1H2NZBgBHmcZDCjFFX2pDpG1WFgEIgxLiOKWehKNuqh7wFG3udXwCFqeRZ\nd8qu+ISe7/9XyWuyUagpLyYo+9c6S55lViZg7nPgQI1TrPlv5ApzIIgUNJFqe/jj\n1rAkdpgbudC112Z3cWikIl+kBbhexZwovp/hA3wJ1uvtZYkyFIfJwC6HZxVJSyYk\n73qS7Sb0RPM6K5zuvYKnb7KgeUOsVWdg/xo0WVwwVsHiHjBv7w+tcJU3yq753+MH\ndqfZe3lbmQpsBA4b+ov7wB1SN++v34mtceGvn9BX1xNQ+lq15iSCcxMZLDCmBVM2\nwCzfoWRNAgMBAAECggEAIef9y+FDDwQw+h5HASNXg3iaxIHmse1TiPkcV73Oa4up\nRlBYNg05Ltb1p1ZKS/zV3XUYTlfxbW/3VjHTecSKji3WCqwVBqY5DoItOU32t47q\n5eeV1wfkWG+PPmfLn8Mv2Nt4VxYIVbGJOyQ58jWNfGThZO+O9NfBM1eGkKFvKYBs\nkYoWKQDaf5ujGLpFrL5sOFM2tReXBR1Rfa0Oa8BhkQqke/D4qbzVVTPL+uOKicyL\nroWtERxGguvLW5HMGJYDhNTJh5GkkdTBk2aD9UIRq9cISxEX32Xj+1sNZvkvBIG7\n7Iz/I3L6XUEx0HF/SAuWWxbaDAcOYiRJxdd3SKIZWQKBgQDRAvApllm0SBe1b6br\nxGDnTjuSmDO55OeqbSiwDJv0dcbhH+OsS+by/2IYInJ/JFDT3rwYQRtRum8O+Aq4\nbTGNckiiBM0llvXLbm59CpMtbRlEpeypISEKJ47QF96h+eXaVZPqwL7PCFAINxxh\neGoT8wWYniwVw/LSN2+P7b17YwKBgQCw5IoVNFnKaUtdJysXXzD3H5VDgyUt24PA\nfCKRRlhuAMS5xpkxP4xE4ecuoU7a8A6Z6d0eycpGxZkxnEnZVu3kSMtmkIu6HNgh\n6TpcD90ZnkoxwYrqpTtaE01GZ9yua0GF15Gh3qNHhXGP2Vq70YUCcIbIiKApGxCK\nvs2uvxYojwKBgHirlpacDExOdwm0XY2vAjdo7nHzV6HSq4G0phIGJaAcw2bEL4ER\nDVRr52mBsdL/136LENN7+1bTKT1eLWpO+JXuTkrkNMCoCF6b8kRU76YBX95HYXw/\n+UBQmF5B+bJQgcjtMYoOH9uNtA8aKlOH3s6Ht0pmv5MNX0rI4KsbGhN7AoGAWYvX\nutQ9gBG9bPKfBb3Sc8cxMHP7JjOxhodQmGob6dPJwqGeeyfIQjZ5aUmPOZW8Tn3s\nyeEs3Ja67jpHyBYRZzbSgKE7moNvhfsi5+e/7XAL7xQi1pW+beLHg5SgSktRaAew\nWVjzHwmWa1OEcv+lbY65LFq9eRGSViowxP1GolECgYEAynb4EwAA4LkqIzYl2CRF\nAz8k7cU71Uusas2W3bKh8N2MsHelXD4yNFYsSTfxkmfmaGfbpaZ8pOFxIiQYWzeU\n5rc5VHzUBBzNZYfnjfJzI4zjXlEw2KYrudBTdRuQiDcgIupxUid/V+pS81sTvC2C\nCz8P0jVCGDa8f4ZiTB/Qb8o=\n-----END PRIVATE KEY-----",
  "keyAlgorithm":"RSA_2048",
  "serviceAccountId":"iqKpEF3URCe0yAsyrsk_4g"
}