How do I use the Backupify for G Suite API?

Question

How do I access and use the Backupify for G Suite API?

Environment

• Backupify 1.0 for G Suite
• Datto SaaS Protection 1.0 for G Suite

Overview

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:

1. Sign in to SaaS Protection/Backupify as the account owner.
2. Access Account Settings.
3. 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
• Authentication

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
• Get a User
• Add a User
• Delete a User

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

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

 Error Status

 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

 Error Status 

 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 

 Example Response 

No Content.

 Status Codes 

 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

 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 

 Error status 

 Example Request(s) 

curl https://api.backupify.com/gapps/v1/domains/backupify/services/42

Export Management API

• List Exports
• Get Export
• Start Export

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 

 Error Status

 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 

 Error Status 

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

Error Status 

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.