Overview
Most requests to the CrashPlan API must be authenticated. This article describes the available CrashPlan API authentication methods and provides examples of their use.
Considerations
- The examples in this article use curl, but the concepts apply to other tools that can be used to interact with the CrashPlan API.
- Although basic authentication is deprecated, you can still use basic authentication to obtain a token.
Comparison of CrashPlan API authentication methods
The CrashPlan API offers the following authentication methods:
- Obtain a token with an API client: You obtain a temporary authentication token that is good for 15 minutes and use it to authenticate API requests.
- Use basic authentication (deprecated): You provide your username and password to authenticate each API request.
- Use basic authentication to obtain a token: You obtain a temporary authentication token that is good for 30 minutes and use it to authenticate API requests.
The following table describes the advantages and disadvantages of each authentication method:
Authentication method | Advantages | Disadvantages |
---|---|---|
Obtain a token with an API client |
|
|
Use basic authentication |
Simple to use |
|
Use basic authentication to obtain a token |
|
|
Obtain a token with an API client
To obtain a token, first create an API client.
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"
Use basic authentication
Basic authentication is deprecated. Instead, use basic authentication to obtain a token.
To use basic authentication, include your CrashPlan username in the API request and supply your password when prompted.
curl -u "username" <request_url>/api/v1/Computer
Replace <request_url>
with the address of your CrashPlan environment (do not include the brackets in your request).
You can use basic authentication for any version 1 or 4 and later resource, and version 3's /auth/jwt resource.
Use basic authentication to obtain a token
Request URLs
The request URL you use in your authentication request depends on your CrashPlan cloud address. Use the following request URLs:
- United States
- Ireland
Step 1: Get the token
- Include your CrashPlan username in a GET request to auth/jwt and supply your password when prompted.
curl -u "username" '<request_url>
/api/v3/auth/jwt?useBody=true'
Replace <request_url>
with the address of your CrashPlan environment (do not include the brackets in your request).
Authentication cookies are not supported
You must include the?useBody=true
query parameter in the auth/jwt
request to return the token in the response body. Omitting the ?useBody=true
query parameter or using ?useBody=false
results in the token being returned in an authentication cookie, which is not supported by the CrashPlan API. Include the returned token in subsequent API requests using the authorization header with the Bearer scheme, for example,
-H 'authorization: Bearer <token>'
If your organization uses two-factor authentication for local users, you must also include a totp-auth header value containing the six- to eight-digit Time-based One-Time Password (TOTP) supplied by the Google Authenticator mobile app. (Sending the request without the TOTP displays the error message TIME_BASED_ONE_TIME_PASSWORD_REQUIRED
.) The example below includes a TOTP value of 424242.
-
curl -u "username" -H "totp-auth: 424242" '
<request_url>
/api/v3/auth/jwt?useBody=true' - From the reply, copy the value of the v3_user_token. In the example below, it is
eyJjdHki...txd546Eg
{"data":{"v3_user_token":"eyJjdHki...txd546Eg"},"error":null,"warnings":null}
Step 2: Use the token in API requests
Include that token in API requests. For example:
tkn="eyJjdHki...txd546Eg"
curl --header 'Authorization: Bearer '$tkn <request_url>/api/v1/User
curl --header 'Authorization: Bearer '$tkn <request_url>
/api/v3/org/<organizationID>
/user
curl -H 'Authorization: Bearer '$tkn <request_url>
/api/v4/role/view
Replace <request_url>
with the address of your CrashPlan environment (do not include the brackets in your request).