Page Comparison

...

...

1. The client requests a resource, without providing any credentials.
2. An HTTP response code 401 (Unauthorized) is returned.
3. The client requests the resource providing the credentials.
   
   1. If authentication fails, the server returns an HTTP response code 401 (Unauthorized), indicating a Bad Credentials or a User is disabled error.
   2. If authentication succeeds but the user does not have enough privileges to access the requested resource, an HTTP response code 403 (Forbidden) indicating a Denied Access error is returned.
   3. If authentication is successful, the server returns an HTTP reponse code 200 (OK), the requested resource, and an authentication token that the client can use to authenticate future requests.
      The authentication token is a session cookie
4. The client requests another resource, providing the authentication token

...

< HTTP/1.1 401 Unauthorized
< Server: Apache-Coyote/1.1
< WWW-Authenticate: Basic realm="Abiquo API"
< Content-Type: text/html;charset=utf-8
< Content-Length: 1152
< Date: Fri, 02 Jul 2010 09:40:14 GMT

...

Response Headers: Content-Length, Content-Type, Date, SetX-Abiquo-CookieToken.
Response Message Body: N/A.
Response Status: 200, 401, 403.
Example Response: Response of the authenticated GET over a Datacenters resource

< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< SetX-Abiquo-CookieToken: auth=YWRtaW46MTI3ODA2NjA1MjM5NDowMjNmNTdkOWMxMzY3NmFjOTVmZjFlMDkyZjQyM2NmOQ; Expires=Fri, 02-Jul-2010 10:20:52 GMT; Path=/api
< Content-Type: application1169dbbca2c1123455ab6b5a06b2b38756fb
< Content-Type: application/vnd.abiquo.datacenters+xml
< Content-Length: 420
< Date: Fri, 02 Jul 2010 09:50:52 GMT
<
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<datacenters>
    <datacenter>
        <link href="http://example.com/api/admin/datacenters/1" rel="edit"/>
        <link href="http://example.com/api/admin/datacenters/1/racks" rel="racks"/>
        <link href="http://example.com/api/admin/datacenters/1/remoteServices" rel="remoteServices"/>
        <id>1</id>
        <location>Redwood city</location>
        <name>myDatacenter</name>
    </datacenter>
</datacenters>

After a successful request, the response will contain the X-Abiquo-Token header with an authentication token that can be used in subsequent requests, as described in the Token Based Authentication section.

Request a resource providing

...

valid credentials but with insufficient privileges

Request Headers: Accept, Content-Type, CookieAuthentication.
Request Parameters: N/A.
Request Message Body: N/A.
Request example: Retrieve all the datacenters

% curl --verbose 'http://example.com/api/admin/datacenters/' \
        -X GET \
        -H "Accept: application/vnd.abiquo.datacenters+xml" \
        -H "CookieAuthorization: auth=YWRtaW46MTI3ODA2NjA1MjM5NDowMjNmNTdkOWMxMzY3NmFjOTVmZjFlMDkyZjQyM2NmOQBasic ZXhhbXBsZTpleGFtcGxl"

> GET /api/admin/datacenters HTTP/1.1
> User-Agent: curl/7.19.5 (x86_64-pc-linux-gnu) libcurl/7.19.5 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.15
> Host: example.com
> CookieAuthorization: auth=YWRtaW46MTI3ODA2NjA1MjM5NDowMjNmNTdkOWMxMzY3NmFjOTVmZjFlMDkyZjQyM2NmOQBasic ZXhhbXBsZTpleGFtcGxl
> Accept: application/vnd.abiquo.datacenters+xml

Response Headers: Content-Length, Content-Type, Date.
Response Message Body: N/A.
Response Status: 200, 401, 403.
Example Response: Response of the authenticated GET over a Datacenters resource, but without enough privileges

< HTTP/1.1 200403 OKForbidden
< Server: Apache-Coyote/1.1
< Content-Type: application/vnd.abiquo.datacenters+xmltext/html;charset=utf-8
< Content-Length: 4201021
< Date: Fri, 02 Jul 2010 09:5659:3542 GMT
<
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<datacenters>
    <datacenter>
        <link href="

Token based authentication

To avoid exposing user credentials, Abiquo provides a token based authentication. For each authenticated request, Abiquo generates an authentication token that can be used to make requests to the API without the need of passing the credentials. Each HTTP response contains a header with an expirable token that can be used to perform requests to the API. In order to use the otken based authentication, the client must send it in the "Authorization" header, as follows:

Authorization: Token authentication-token

After a successful request, the response will contain the X-Abiquo-Token header with a new token that can be used in subsequent requests.

Request a resource without providing credentials

Request Headers: Accept, Content-Type.
Request Parameters: N/A.
Request Message Body: N/A.
Request example: Retrieve all the datacenters

% curl --verbose 'http://example.com/api/admin/datacenters/' \
        -X GET \
        -H "Accept:application/vnd.abiquo.datacenters+xml"

> GET /api/admin/datacenters HTTP/1.1
> User-Agent: curl/7.19.5 (x86_64-pc-linux-gnu) libcurl/7.19.5 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.15
> Host: exmaple.com
> Accept: application/vnd.abiquo.datacenters+xml

Response Headers: Content-Length, Content-Type, WWW-Authenticate, Date.
Response Message Body: N/A.
Response Status: 200, 401, 403.
Example Response: Response of the unauthenticated GET over a Datacenters resource

< HTTP/1.1 401 Unauthorized
< Server: Apache-Coyote/1.1
< WWW-Authenticate: Token realm="Abiquo"
< Content-Type: text/html;charset=utf-8
< Content-Length: 1152
< Date: Fri, 02 Jul 2010 09:40:14 GMT

Request a resource providing valid credentials

Request Headers: Accept, Content-Type, Authentication.
Request Parameters: N/A.
Request Message Body: N/A.
Request example: Retrieve all the datacenters

% curl --verbose 'http://example.com/api/admin/datacenters/1" rel="edit"/>' \
        <link href="http://example.com/api/admin/datacenters/1/racks" rel="racks"/>-X GET \
        <link-H href="httpAccept:application//example.com/api/admin/datacenters/1/remoteServices" rel="remoteServices"/>vnd.abiquo.datacenters+xml" \
         <id>1</id>
 -H "Authorization: Token 1169dbbca2c1da4da5ab6b5a06b2b38756fb"

> GET /api/admin/datacenters HTTP/1.1
> <location>Redwood city</location>
        <name>myDatacenter</name>
    </datacenter>
</datacenters>

Request a resource providing valid credentials but with insufficient privileges

...

User-Agent: curl/7.19.5 (x86_64-pc-linux-gnu) libcurl/7.19.5 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.15
> Host: example.com
> Authorization: Token 1169dbbca2c1da4da5ab6b5a06b2b38756fb
> Accept: application/vnd.abiquo.datacenters+xml

Response Headers: Content-Length, Content-Type, Date, X-Abiquo-Token.
Response Message Body: N/A.
Request Message Body: N/A.
Request example: Retrieve all the datacentersResponse Status: 200, 401, 403.
Example Response: Response of the authenticated GET over a Datacenters resource

% curl --verbose 'http://example.com/api/admin/datacenters/' \
        -X GET \
        -H "Accept< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< X-Abiquo-Token: 1169dbbca2c1123455ab6b5a06b2b38756fb
< Content-Type: application/vnd.abiquo.datacenters+xml" \
        -H "Authorization: Basic ZXhhbXBsZTpleGFtcGxl"

> GET /api/admin/datacenters HTTP/1.1
> User-Agent: curl/7.19.5 (x86_64-pc-linux-gnu) libcurl/7.19.5 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.15
> Host: example.com
> Authorization: Basic ZXhhbXBsZTpleGFtcGxl
> Accept: application/vnd.abiquo.datacenters+xml

Response Headers: Content-Length, Content-Type, Date, Set-Cookie.
Response Message Body: N/A.
Response Status: 200, 401, 403.
Example Response: Response of the authenticated GET over a Datacenters resource, but without enough privileges

< HTTP/1.1 403 Forbidden
< Server: Apache-Coyote/1.1
< Set-Cookie: auth=YWRtaW46MTI3ODA2NjU4MjkzMzo5ZGQ0NGYxZTk2NWNlNjk3Nzg3YTZlYmZkNmVlM2QwMA; Expires=Fri, 02-Jul-2010 10:29:42 GMT; Path=/api
< Content-Type: text/html;charset=utf-8
< Content-Length: 1021
< Date: Fri, 02 Jul 2010 09:59:42 GMT
< Content-Length: 420
< Date: Fri, 02 Jul 2010 09:50:52 GMT
<
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<datacenters>
    <datacenter>
        <link href="http://example.com/api/admin/datacenters/1" rel="edit"/>
        <link href="http://example.com/api/admin/datacenters/1/racks" rel="racks"/>
        <link href="http://example.com/api/admin/datacenters/1/remoteServices" rel="remoteServices"/>
        <id>1</id>
        <location>Redwood city</location>
        <name>myDatacenter</name>
    </datacenter>
</datacenters>

Two factor authentication

With Basic Authentication, Abiquo can protect user accounts with a two factor authentication code. When two factor authentication is enabled, users will be required to provide an additional verification code to prove their identity. That token will be delivered to the user by Abiquo, using the configured mechanism. Currently there are two supported ways of getting the verification code:

...

% curl -v -u admin:xabiquo http://example.com/api/login -H "Accept:application/vnd.abiquo.user+xml"

> GET /api/login HTTP/1.1
> Authorization: Basic YWRtaW46eGFiaXF1bw==
> User-Agent: curl/7.38.0
> Host: example.com
> Accept:application/vnd.abiquo.user+xml


< HTTP/1.1 401 Unauthorized
< Server: Apache-Coyote/1.1
< Set-Cookie: auth=""; Expires=Thu, 01-Jan-1970 00:00:10 GMT; Path=/api
< WWW-Authenticate: Basic realm="Abiquo Api"
< X-Abiquo-OTP: required; type=GOOGLE_AUTHENTICATOR

...

That header indicates that the verification code is missing, and the type parameter indicates how the user can get it. The possible values are:

...