Required Authorization

All REST API requests must be sent over the secure HTTPS protocol. Also, each REST API implementation needs to authenticate with valid user credentials to obtain a session cookie or authorization token.

If authenticating using a local user credentials a session cookie is returned.
If authenticating using IDP user credentials an authorization token is returned.

See the following tabs for details on each authentication method:

Local User

To get a session cookie, execute an Initiate User Session command with your credentials. The response includes a "calypso-session-id" cookie. All API requests must be made with a valid session cookie in the request header. Web browsers and browser-based REST tools should handle cookie management automatically. Browser-less interactions may require cookie headers to be manually managed.

IDP User

To get an authorization token, execute an Initiate IDP User Session command with the API key/secret pair that was generated in the web interface (see Generating an API Key and Secret for IDP Users). The response includes an authToken value. All API requests require a valid authorization token in the Authorization header, using the Bearer authentication method. Web browsers and browser-based REST tools should handle Bearer token management automatically. Browser-less interactions may require Authorization headers to be manually managed.

To terminate the session, execute a Delete a User Session. You can check if a session exists or is valid with a Get User Session Info command. See Authentication Resources for more details on these commands.

Also, each API command listed in REST API Reference includes an "Authorizations" heading that lists the permission necessary to execute the command. If you make an API call using a login that is not authorized to execute the command, a 403 Forbidden error response is returned, which is described in Errors.