Backupify/Datto SaaS Protection 1.0 for G Suite: How do I access and use the API for Backupify 1.0 for G Suite?

Follow

Question 

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

Environment

  • Backupify/Datto SaaS Protection 1.0 for G Suite

Answer

The Backupify/Datto SaaS Protection for G Suite API makes it easy for Enterprise customers to manage their Backupify/Datto SaaS Protection account. Currently, the API facilitates user management within your Backupify/Datto SaaS Protection account?

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. By default, keys are not created for your account.

Generating your keys

  1. Sign in to Backupify/Datto SaaS Protection as the account owner.
  2. Access Account Settings.
  3. Choose the API Tokens tab and click Generate API Keys
You can regenerate or delete your keys at any time in the API Tokens tab. Regenerating or deleting keys renders all earlier keys invalid, and you must re-enter the newest keys before reaccessing the API.

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 request 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
}

The element 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 will package errors in this form:

{
     message: 'Some attributes were invalid.'
     errors: [
     {
          field: 'first_name'
          message: 'Can't have special characters.'
   } ]
}

If you encounter a server error 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. The user's status can be 'archived' or 'active.' The default status 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

email

string

User's email

name

string

User's full name

status

string

Status indicating whether the 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

Human-readable name of the service, i.e., Google Mail Service, Google Docs Service, etc.

link

string

URL to retrieve detailed status information about a single service

service_id

integer

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 users exist with that email within the application; or 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

There are not any users with that email within the application or the current domain, or you don't 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

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 There are not any user with that email was found within the application or the current 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 This attribute indicates whether a backup is currently 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 This field is 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 This attribute represents how much data we have backed up for this service.
user_email string The 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",
     "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 works on the export began, in ISO-8601 format. Null if work has not yet begun.
ended_at string The time that works on the export was completed, in ISO-8601 format. Null if work has not yet completed.
state string This attribute represents the current status 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 The location where the export can be downloaded. Null until the export completes.

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/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 This attribute provides 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

Was this article helpful?

0 out of 0 found this helpful

You must sign in before voting on this article.

Want to talk about it? Have a feature request?

Head on over to our Community Forum or get live help.

For more Business Management resources, see the Datto RMM Online Help and the Autotask PSA Online Help .

Datto Homepage