Printer Sharing API

This reference describes the Google Cloud Print service interfaces that are used by application developers to share printers associated with an authenticated account.

Every API call you make must contain the following Authorization HTTP header: Authorization: OAuth YOUR_ACCESS_TOKEN, where YOUR_ACCESS_TOKEN refers to an OAuth2 access token. To fetch an access token, you will need to make use of the refresh token already stored with your application. For more information on using OAuth2 in this context, see here. Note also that the interfaces which may cause database writes (/share and /unshare) require a valid XSRF token.

All responses are returned in JSON format.

Note: This API is now the only supported printer sharing API. The old API (which used the "APPENDER" role) has been turned off as of November 20, 2013.

Printer ACL

To request a printer's access control list (ACL), call the /printer interface. The returned printer object's "access" field stores an array of printer ACL entries. For example:

access: [
  {
    "role": "OWNER",
    "scope": "johndoe@gmail.com",
    "name": "John Doe",
    "type": "USER",
    "membership": "MANAGER"
  },
  {
    "role": "USER",
    "scope": "janeroe@gmail.com",
    "name": "Jane Roe",
    "type": "USER",
    "membership": "MANAGER",
    "is_pending": true
  }
]

ACL entry fields are the following:

  • role: access level granted to the scope, can be one of the following (robot accounts are not exposed via this API):
    • USER
    • MANAGER
    • OWNER
  • scope: id of the scope (user or group email or domain) to which access rights are granted
  • name: scope display name (can be empty)
  • type: entry type, can be one of the following:
    • USER
    • GROUP
    • DOMAIN
  • membership: rights the logged-in user is granted with within this entry. Note that these rights have nothing to do with the printer access; they indicate what the logged-in user can do with this entry. Only a MANAGER can remove the entry from printer's ACL. Can be one of the following:
    • NONE
    • MEMBER
    • MANAGER
  • is_pending: set to true when the scope owner this printer was shared with has not accepted the invitation yet. Optional, omitted when set to false.

Roles

RoleDescriptionAllowed operations
OWNER User or group who owns the printer. There must be only one scope with role OWNER per printer. Owner entries are created during printer registration only. All operations.
MANAGER User or group has administrator privileges. All allowed for USER role plus:
  • edit printer's properties
  • share the printer
USER Regular printer user.
  • read printer's properties
  • lookup printer
  • submit jobs
DEVICE Printer's robot account. Robot entries are created during printer registration, cannot be modified and are not reported via the sharing API. All, except sharing operations.

Error Handling

For all interfaces, Google Cloud Print will respond with an object containing a Boolean success variable set to false if there was an error in processing the request. There will also be a message variable in the response describing the reason for the error, a numeric error code, and a listing of the request parameters. For example:

{
 "success": false,
 "message": "Missing required parameters.",
 "errorCode": 2,
 "request": { ... }
}

API Simulation Page

GCP provides a simulate page containing HTML forms which provide a convenient way to make requests to the various service interfaces for testing and debugging purposes.
Disclaimer: This page is not an officially supported feature of GCP and any aspect of it may change at any time.

Calling Syntax

To use the interfaces, you need to prepend the Google Cloud Print URL https://www.google.com/cloudprint to the interface names, for example https://www.google.com/cloudprint/share.

/share

The /share interface is used to share printer with a scope (user or group or domain).

Parameters

printerid (required)
The ID of the printer being shared.
scope (required)
Email of the user or group or domain name to share the printer with.
role (required)
The role the user or group is granted with. Can be either USER or MANAGER.
skip_notification (optional)
Set it to true to not send an invitation email to the scope the printer is shared with.

Response

The JSON response object contains a Boolean success indicator, a message, the XSRF token used, and a listing of the request parameters.

/unshare

The /unshare interface is used to delete a scope from the printer ACL.

Parameters

printerid (required)
The ID of the printer to unshare.
scope (required)
Email of the user or group or domain name to delete from the printer's ACL.

Response

The JSON response object contains a Boolean success indicator, a message, the XSRF token used, and a listing of the request parameters.