Question
How do I access and use the Backupify 1.0 for G Suite API?
Environment
- Backupify 1.0 for G Suite
- Datto SaaS Protection 1.0 for G Suite
Answer
The Backupify for G Suite API makes it easy for Enterprise customers to manage their SaaS Protection/Backupify account. Currently, the API facilitates user management within your SaaS Protection/Backupify account. This documentation covers our RESTful API.
Getting Started
If you are an Enterprise or Enterprise+ customer, you'll gain access to our API through two unique keys: Client ID and Client Secret. If you would like to upgrade to an Enterprise-level package to gain access to the Backupify API or if you have any questions, contact Datto support.
By default, no keys are created for your account. To generate your keys:
- Sign in to SaaS Protection/Backupify as the account owner.
- Access Account Settings.
- Choose the API Tokens tab and click Generate API Keys.
The API keys authenticate the retrieval of your OAuth2 tokens and allow access to the full Backupify Google Apps API, as well as every domain and subdomain within your account. These keys are unique to you and you should keep them secret.
Once you have retrieved an access token, you should include it in the request headers for every API request under the Access-Token header. All requests must be made via HTTPS/SSL for security.
Using Tokens
Generating Access Tokens
Using your client_id and client_secret, you can make a request for an access token from https://api.backupify.com/oauth/token. For example:
curl -XPOST https://api.backupify.com/oauth/token --data-urlencode 'client_id={client_id}' --data-urlencode 'client_secret={client_secret}' -d 'grant_type=client_credentials&scope=write'
Example response:
{
'access_token':
`hhZkpodIrH1mRV8hmhSMxH9oOKRZH5xDnLYa8hL9YJrVFRfXwVuypVkgZVOiU+zba Io30yCeQXG7jLRvYGZURg=='
'token_type':
'bearer' 'expires_in': 899
}
where "expires_in" is listed in seconds.
If any credentials were malformed or are insufficient, you will receive an error.
Example Error:
{
'error': 'invalid_client'
'error_description': 'The client identifier provided in invalid, the client failed to
authenticate, the client did not include its credentials, provided multiple client
credentials, or used unsupported credentials type.'
}
Authentication
Every request must be accompanied by an access token in the Authorization header as follows:
curl -H 'Authorization: {AccessToken}' https://api.backupify.com/gapps/{APIVersion}/{Endpoint}
An invalid access token will result in a 401 Unauthorized error.
Errors
Responses to client errors that require additional information to be sent will package errors in this form:
{
message: 'Some attributes were invalid.'
errors: [
{
field: 'first_name'
message: 'Can't have special characters.'
} ]
}
If a server error is encountered when processing a request, the server will issue a 500 error.
If the Google Apps API is down for maintenance, a request will result in a 503 error.
User Management API
List Users
List Users retrieves a paginated list of users for the given domain. API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/users
Allowed Method: GET
Parameters
| PARAMETER | TYPE | REQUIRED? | DESCRIPTION |
| status | string | No | The type of users you would like to retrieve, by status. Can be 'archived' or 'active'. The default is 'all'. |
| page | integer | No | The number of pages of users to skip. |
| per_page | integer | No | The number of users to return. The maximum is 100. The default is 25. |
Example response
{
"next_page": 'nextPageLink',
"total_entries": 25,
"users": [
{
"name": 'user.full_name'
"email": 'user.email',
"status": 'user.status',
"org_unit": 'user.org_unit_name'
"service_status":
{
"service_name":
{
"link": 'service.link',
"service_id": 'service.id',
"status": 'service.status'
}
}
} ]
}
Attributes
| NAME | TYPE | DESCRIPTION |
| next_page | string | The url to fetch the next page of users. |
| total_entries | integer | The total number of users. |
| users | array | An array of user objects. |
Error Status
|
HTTP Status Code |
Reason |
|
200 |
Success |
Example Request(s)
curl https://api.backupify.com/gapps/v1/domains/backupify/users curl https://api.backupify.com/gapps/v1/domains/backupify/users?page=2&per_page=50
Get a User
Get a User retrieves a user.
API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/users/{UserEmail}
Allowed Method: GET
Example Response
{
"email": 'user.email',
"name": 'user.full_name',
"status": 'user.status',
"org_unit": 'user.org_unit_name',
"service_status":
{
"service_name":
{
"link": 'service.link',
"service_id": 'service.id',
"status": 'service.status'
}
}
}
Attributes
|
NAME |
TYPE |
DESCRIPTION |
|
|
string |
User's email. |
|
name |
string |
User's full name. |
|
status |
string |
Status indicating whether user is active or archived. |
|
org_unit |
string |
User's organizational unit's name. |
|
service_status |
hash |
Contains a summary of service statuses keyed by name. |
|
service_name |
string |
The human readable name of the service i.e., Google Mail Service, Google Docs Service, etc. |
|
link |
string |
The url to retrieve detailed status information about a single service. |
|
service_id |
integer |
The unique ID for the service. |
|
status |
string |
Either 'partial' or 'complete'. If we have successfully backed up all scheduled files then this field will read 'complete'. If we have missed a file and need to retry in the future this field will read 'partial'. |
Error Status
|
HTTP Status Code |
Reason |
|
200 |
Success |
|
404 |
No user with that email was found within the application or within the current domain. |
Example Request(s)
curl https://api.backupify.com/gapps/v1/domains/backupify/users/bob.smith@backupify.com
Add a User
Add a User adds a user to the given domain in SaaS Protection/Backupify. API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/users -d 'user[email]={UserEmail}'
Allowed Method: POST
Data
|
Data Attribute |
Description |
|
user[email] |
The user's email. |
Example Response
No Content.
Status Codes
|
HTTP Status Code |
Reason |
|
200 |
The user already exists in the application. |
|
201 |
The user was added to the application. |
|
400 |
The user[email] parameter was not provided, or was incorrectly formatted. |
|
402 |
The user was not added due to a billing issue. Please contact Datto for more information. |
|
404 |
No user with that email was found within the domain or you do not have access to the specified domain. |
Example Request(s)
curl -X POST https://api.backupify.com/gapps/v1/domains/backupify/users -d 'user[email]=bob.smith@backupify.com'
Delete a User
Delete a User removes the user from the given domain in SaaS Protection/Backupify. WARNING: This is not reversible, and the deleted user and their data will no longer be accessible within Backupify.
API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/users/{UserEmail}
Allowed Method: DELETE
Example Response
No content
Status codes
| HTTP Status Code | Reason |
| 200 | The user was removed successfully. |
| 404 | No user with that email was found within the domain. |
Example Request(s)
curl -X DELETE https://api.backupify.com/gapps/v1/domains/backupify/users/bob.smith@backupify.com
Get a Service
Get a Service retrieves detailed status information for a service.
API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/services/{ServiceID}
Allowed Method: GET
Example Response
{
"id": 42,
"service_type": 'Google Mail Service',
"user_email": "bob.smith@backupify.com",
"last_attempted_backup": '2014-02-19T16:50:48Z',
"last_successful_backup": '2014-02-19T16:50:48Z',
"status": 'complete'
"backup_in_progress": false,
"storage": '38.7 MB'
}
Attributes
| Name | Type | Description |
| backup_in_progress | boolean | Indicates whether a backup is currenly in progress for this service. |
| id | integer | The unique ID for the service. |
| last_attempted_backup | string | The last time a backup was attempted in ISO-8601 format. |
| last_successful_backup | string | The last time a backup completed successfully in ISO-8601 format. |
| service_type | string | The human readable name for this service. |
| status | string | Either 'partial' or 'complete'. If we have successfully backed up all scheduled files then this field will read 'complete'. If we have missed a file and need to retry in the future this field will read 'partial'. |
| storage | string | How much data we have backed up for this service. |
| user_email | string | Email of the user the queried service belongs to |
Error status
| HTTP Status Code | Reason |
| 200 | Success |
| 404 | No service with that ID was found within the current domain. |
Example Request(s)
curl https://api.backupify.com/gapps/v1/domains/backupify/services/42
Export Management API
List Exports
List Exports retrieves a list of all exports created in the past 30 days for a given service.
API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/services/{ServiceID}/exports
Allowed Method: GET
Example Response
{
"total_entries": 1,
"exports": [
{
"id": 1,
"service_id": 19,
"created_at": "2014-03-10T18:41:07Z",
"started_at": "2014-03-10T18:41:08Z",
"ended_at": null,
"state": "working",
"result_email_destination": "admin@backupify.com", "archive_url": null
} ]
}
Attributes
| Name | Type | Description |
| total_entries | integer | The total number of exports. |
| exports | array | An array of export objects. |
Error Status
| HTTP Status Code | Reason |
| 200 | Success |
| 404 | No service with that ID was found within the current domain. |
Example Request(s)
curl https://api.backupify.com/gapps/v1/domains/backupify/services/200/exports
Get Export
Get Export retrieves information about a given export, assuming it was created in the past 30 days.
API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/services/{ServiceID}/exports/{ExportID}
Allowed Method: GET
Example Response
{
"id": 1,
"service_id": 19,
"created_at": "2014-03-10T18:41:07Z",
"started_at": "2014-03-10T18:41:08Z",
"ended_at": null,
"state": "working",
"result_email_destination": "admin@backupify.com",
"archive_url": null
}
Attributes
| Name | Type | Description |
| id | integer | The ID of the export. |
| service_id | integer | The ID of the service the export belongs to. |
| created_at | string | The time that the export was created at, in ISO-8601 format. |
| started_at | string | The time that work on the export began, in ISO-8601 format. Null if work has not yet begun. |
| ended_at | string | The time that work on the export was completed, in ISO-8601 format. Null if work has not yet completed. |
| state | string | The state of the export; queued, working, successful, failed, or canceled. |
| result_email_destination | string | The email address to notify when the export has been completed. |
| archive_url | string | Where the export can be downloaded from. Null until the export is completed. |
Error Status
| HTTP Status Code | Reason |
| 200 | Success |
| 404 | No service or export with the given IDs was found within the current domain, or the export with that ID was created over 30 days ago. |
Example Request(s)
curl https://api.backupify.com/gapps/v1/domains/backupify/services/200/exports/21
Start Export
Start Export starts an export for a given service.
API Endpoint - https://api.backupify.com/gapps/v1/domains/{DomainName}/services/{ServiceID}/exports
Allowed Method: POST
Example Response
{
"id": 5,
"state": "queued"
}
Attributes
| Name | Type | Description |
| id | integer | The ID of the export that has been created. |
| state | string | The state of the export; queued, working, successful, failed, or canceled. |
Error Status
| HTTP Status Code | Reason |
| 200 | Your request was successful, but an export for this service is already in progress. |
| 201 | An export was created. |
| 404 | No service with the given ID was found within the current domain. |
| 500 | The export failed to be created or enqueued in our system. |
Example Request(s)
curl -X POST https://api.backupify.com/gapps/v1/domains/backupify/services/200/exports
To contact Backupify/Datto SaaS Protection support, click here to submit a Support Request, or click here for more contact options.