Previous: Introduction | Up: Introduction | Next: Basic Authentication

Authentication

Most API calls require authentication as a registered user of the CloudForge services. This must initially be established by providing a credentials parameter set in the request. The credentials (domain, username, and password) should identify the end user making the request (not necessarily the developer of the application).

If authentication is successful, a session cookie will be included in the response; subsequent requests that include a valid session cookie do not need to include the credentials parameters. If no session cookie is provided, the system will expect to receive with the credentials parameters to re-authenticate.

It is preferred that the session cookie be used for subsequent requests within the session, rather than resubmitting the credentials.

Credential Parameters

Credentials are broken down into two groups, developer credentials and user credentials.

The developer credentials are used to identify which application is accessing the system. These credentials are needed for all requests within the API (unless you are using a valid session cookie).

The developer key will be accessible by Organization Owner or Administrator from CloudForge UI.

The developer credentials are:

The user credentials are used to identify the operator of the application (the end user).

These credentials are needed for most API methods, but not all; the API documentation will indicate if these credentials are NOT needed. The API call to create a new organization, for example, will not need these credentials, since the organization will not have been created yet.

The user credentials are:

User key can be obtained from My Settings page of the user.

Testing Credentials

Since all API requests may be sent along with valid credentials, there is no need to make an API call just to "log in". However, a login function is provided for testing.

Request Format:

POST /api/1/login.[json|xml]

Parameters:

The login request expects to receive both developer and user credential parameters.

Response Format:

On success, returns 200 (Success) and this content:

<?xml version="1.0" encoding="UTF-8"?> <hash> <responseHeader> <accepted type="integer">1</accepted> </responseHeader> </hash>
{ "responseHeader": { "accepted": 1 } }

On failure, will return a simple 401 (Unauthorized) status response.