# REST services

LL::NG portal is a REST server that gives access to configuration, session and also authentication.

## Portal REST services

### Authentication

The authentication service is always available with REST, you just need to send credentials on portal URL. But by default, the portal is protected by one time tokens to prevent CSRF. You must disable them or set a rule (configuration parameter `requireToken`) so token will not be required for REST requests, for example:

    $env->{HTTP_ACCEPT} !~ m:application/json:

#### API

Request parameters:

- Endpoint: `/`
- Method: `POST`
- Request headers:
  - `Accept`: `application/json`
- POST data:
  - `user`: user login
  - `password`: user password
  - xxx: optional parameters, like `lmAuth` if your portal uses `Choice` or `spoofId` to impersonate.

The JSON response fields are:

- `result`: authentication result, `0` if it fails, `1` if it succeed
- `error`: error code, the corresponding error can be found in `Lemonldap::NG::Portal::Main::Constants`
- `id`: if authentication succeed, the session id is returned in this field

You can also get the cookie by reading the response header `Cookie` returned by the portal.
Before version 2.0.4, the response to a success authentication had no `id` field, and `error` field was named `code` (use Cookie header to get id value).

#### Example

- Request with curl:

    curl -H "Accept: application/json" -d user=rtyler -d password=rtyler http://auth.example.com/ | json_pp

With `cURL > 7.18.0`, to include special characters like @, & or + in the cURL POST data:

    curl -H "Accept: application/json" -d name=rtyler --data-urlencode passwd=@31&3+*J http://auth.example.com/ | json_pp

- Response for bad authentication:

    {
        "result" : 0,
        "error" : 5
    }

- Response for good authentication:

    {
        "result" : 1,
        "error" : "0",
        "id" : "b048bf87ca401da1d89419813e3acf466d5e4465fe3a1f7adfd8240bd161bde2"
    }

### Sessions

REST functions for sessions are protected by Web Server, you can change this in portal configuration.

See REST session backend documentation for more.

### Configuration

REST functions for configuration are protected by Web Server, you can change this in portal configuration.

See REST configuration backend documentation for more.