Overview
API clients authenticate access to CrashPlan APIs. An API client contains a client ID and a secret that you submit for authentication much like a username and password. Create an API client for each API integration or script that requires access to the CrashPlan API.
If you create your own integration or scripts using CrashPlan APIs, submit the client ID and secret with the API to obtain an authentication token to use in your requests.
Considerations
- To create API clients, you must be assigned the Customer Cloud Admin role.
- When you create an API client, the client ID and secret appear only once. Save these in a safe place so that when needed you can submit them for authentication of an API integration or script. If you lose the secret, you must reset the secret.
- When you reset an API client secret, the integration or script using that API client loses its authentication. To restore authentication, you must resubmit the new secret.
- Authentication tokens obtained from an API client expire after 15 minutes.
About API clients
Least privilege
API clients enforce the principal of least privilege. By setting the API permissions of an API client to just the minimal read and write permissions needed, you can ensure that the integration or script using the API client has access to only the necessary parts of CrashPlan.
This model provides great advantage over tying access to a user account because you can limit an API client to a more narrow scope of functionality than you would a user. And because API clients are not tied to a user lifecycle, it means your integration or script is not tied to the employment status of any one individual.
Secrets
All requests to CrashPlan require authentication. For example, when you sign in to the CrashPlan console, you enter your username and password to get authenticated for access. In a similar way, integrations or scripts that connect to CrashPlan need authentication. You could enter a username and password to get authentication, but that is not as secure as using an API client ID and secret.
The secret is what makes an API client powerful. If you uncover a problem with API authentication, such as a security breach, you can reset the API client's secret to immediately stop authentication of any integration or script using that API client. Once the breach is resolved, you simply submit the new secret with the client ID to resume authentication.
FAQs
Can we still use other authentication methods to authenticate API access?
Yes, you can use usernames and passwords (basic authentication) to authenticate API access. But this is not as secure. Usernames and passwords are notoriously liable to being stolen or hacked. So while CrashPlan still supports basic authentication, for the best security you should use API clients. API clients create Oauth 2.0-compliant tokens that provide a high level of security for your API requests.
How do I update my existing API integrations to use tokens from API clients?
If you create your own integration or script using CrashPlan APIs, inventory the integration to find all the places that use basic authentication (username/password). Then replace those instances with commands to create and use tokens generated from API clients.
What happens when a token expires?
Authentication tokens obtained with an API client expire every fifteen minutes. This expiration period ensures that the token authorizes access for the current application session, but doesn't provide access beyond that. If the token expires during the current session, service continues uninterrupted, since authorization was already granted at the beginning of the session. But once the session ends and the token expires, the application is forced to make the API integration or script sign in again with a fresh token. This way the service knows the API integration or script is continually involved in re-authorizing the application. If you create your own integration or script using CrashPlan APIs, to ensure a fresh token for your API requests, write your scripting so that the API client ID and secret are submitted for a new token as part of the request.
API clients in the CrashPlan console
To view API clients:
- Sign in to the CrashPlan console.
- Select Administration > Integrations > API Clients.
Item | Description | |
---|---|---|
a | Create new API client | |
b | Client name |
The name of the API client.
As a best practice, name the API client to reflect the integration or script for which it is used. |
c | Date created | The date and time the API client was originally created. |
d | Last redeemed | The last time the API client's ID and secret were submitted to obtain an authentication token. |
e | Client ID |
The globally unique ID of the client.
Submit this ID with the API client's secret for authentication. (The secret appears only when the API client is created or when you select Actions > Reset API secret.) |
f | Actions | Select to edit, reset, or delete the API client. |
g | Details | Select to view the details of the API client. |
Actions
To perform actions on an API client:
- Click Actions to the right of the API client.
- Select an action.
Command | Description |
---|---|
Edit API client | Edits the API client name, description, and API permissions. |
Reset API secret |
Resets the API client secret.
After resetting, the new secret appears. Copy the new secret and the client ID to a safe place.
When you reset a secret, the API integration or script using that secret loses its authentication. To restore authentication, you must resubmit the new secret with the client ID. |
Delete API client |
Removes the API client.
Before you delete an API client, ensure that no API integrations or scripts use that client. Deleting an API client breaks the API integration or script that uses that client. |
API client details
To see API client details, click the details icon .
Item | Description | |
---|---|---|
a | Actions | Select to edit, reset, or delete the API client. |
b | Date created | The date and time the API client was originally created. |
c | Last redeemed | The last time the API client's ID and secret were submitted to obtain authentication. |
d | Client ID |
The globally unique ID of the client.
Submit this ID with the API client's secret for authentication. (The secret appears only when the API client is created or when you select Actions > Reset API secret.) |
e | API permissions | The API endpoints for which the API client has read and write permissions. |
API permissions
In API client details, API permissions lists the API endpoints that the API client provides permissions to. When you create or edit an API client, select the minimal level of read and write access to ensure least privilege access for your integration or script. Some API endpoints do not offer write permissions because those APIs function solely for reading system information, not creating it.
Manage API clients
Create an API client
Before you create API clients, take an inventory of all your API integrations and scripts. Create one API client for each rather than a single API client for many. This way, if one of your API integrations or scripts is compromised, you need only interrupt that one to either reset a secret or create a new API client so you can resume operation. The more granular your API clients, the more flexible you can be when dealing with issues that require you to create new authentication.
- Sign in to the CrashPlan console.
- Select Administration > Integrations > API Clients.
- Click Create new API client.
The Create new API client dialog appears.
- Enter a name and description.
Make the name specific to the API integration or script that uses the API client. - In API permissions, select the APIs for which the API client has read and write permissions.
- Click Save.
The client ID and secret appear.
- Click the copy button to copy the client ID, secret, and URL to a safe location.
IMPORTANT: This is the only time the secret is displayed. If you lose the secret for this client ID, you must reset the secret. - Click Done.
The new API client is displayed in the CrashPlan console.
Next step: Obtain a token
After you create an API client and have saved the client ID and secret, submit the information to obtain an authentication token.
Request the token with the /api/v3/oauth/token resource:
curl -X POST -u '<clientID>:<secret>' -H "Accept: application/json" "<requestURL>/api/v3/oauth/token?grant_type=client_credentials"
In the example (which uses curl), replace <ClientID>
with the API client ID and replace <Secret>
with the API client secret. Replace <request_url>
with the URL of your CrashPlan cloud instance:
- United States
- Ireland
For example:
curl -X POST -u 'key-79muGw9i424:DWL-mPQ' -H "Accept: application/json" "https://console.eu5.cpg.crashplan.com/api/v3/oauth/token?grant_type=client_credentials"
A successful request returns an authentication token. For example:
{"access_token":"eyJjdHkiO_bxYJOOn28y...5HGtGHgJzHVCE8zfy1qRBf_rhchA","token_type":"bearer","expires_in":900}
Use the authentication token (also known as a bearer token) in all your API requests. For example, following is an API request to get a list of users:
curl -X GET 'https://console.eu5.cpg.crashplan.com/api/v3/users?active=true&blocked=false&pageSize=100' -H "authorization: Bearer eyJjdHkiO_bxYJOOn28y...5HGtGHgJzHVCE8zfy1qRBf_rhchA"
Edit an API client
- Sign in to the CrashPlan console.
- Select Administration > Integrations > API Clients.
- Click Actions on the API client to edit.
- Select Edit API client.
The Edit API client dialog appears.
- Change the client name, description, and API permissions as desired.
- Click Save.
Reset a secret
If you uncover a problem with API authentication, such as a security breach, you can reset the API client's secret. Resetting a secret immediately stops authentication of any API integration or script using the previous secret. Submit the new secret with the client ID to resume authentication.
- Sign in to the CrashPlan console.
- Select Administration > Integrations > API Clients.
- Click Actions on the API client whose secret you want to reset.
- Select Reset API secret.
The Reset API secret dialog appears.
- Click Reset secret.
The client ID and its new secret are displayed. Note that the client ID is unchanged. It is presented in the dialog with the new secret so you can keep them together.
- Click the copy button to copy the client ID and secret to a safe location.
IMPORTANT: This is the only time the new secret is displayed. If you lose the secret for this client ID, you must reset the secret again. - Click Done.
To use the new secret in the API integration or script, submit it with the client ID to obtain authentication. If you create your own integration or script using CrashPlan APIs, submit the client ID and with the API to obtain an authentication token to use in your requests.
Delete an API client
Delete an API client when it is no longer needed. However, before deleting an API client, ensure that no API integrations or scripts use it. Deleting an API client that is still in use results in authentication stopping for the API integration or script using it, and you must create a new API client to replace the deleted one.
- Sign in to the CrashPlan console.
- Select Administration > Integrations > API Clients.
- Click Actions on the API client to delete.
- Select Delete API client.
The Delete API client dialog appears.
- Click Delete.
The API client is deleted.