---
updatedAt: 2025-04-03T21:41:28.000Z
agentTools:
  projectIndex: https://replicated.readme.io/llms.txt
---

# Identity API

Replicated currently supports integration with LDAP.  Identity API provides authentication and syncing with LDAP sever.

> 📘 Identity API Endpoint
>
> The Identity API is part of the [Integration API](https://replicated.readme.io/docs/integration-api-reference).  To discover the Integration API base endpoint, query the `REPLICATED_INTEGRATIONAPI` environment variable from inside your container.

# LDAP Authentication

## /identity/v1/login

Authenticates the user and returns the corresponding entry properties.

### Request payload

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Name
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        username
      </td>

      <td>
        String
      </td>

      <td>
        As defined by the `ldap_username_field` setting
      </td>
    </tr>

    <tr>
      <td>
        password
      </td>

      <td>
        String
      </td>

      <td>
        Cleartext passowrd
      </td>
    </tr>
  </tbody>
</Table>

### Response Status code

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Status
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        200
      </td>

      <td>
        User authenticated successfully
      </td>
    </tr>

    <tr>
      <td>
        401
      </td>

      <td>
        Invalid username or password
      </td>
    </tr>
  </tbody>
</Table>

In case `200` is returned, the body of the response will contain LDAP properties for the authenticated user entry.  The `password` attribute will be omitted from the result.

### Response body

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Name
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        DN
      </td>

      <td>
        String
      </td>

      <td>
        LDAP DN for the user's entry
      </td>
    </tr>

    <tr>
      <td>
        Username
      </td>

      <td>
        String
      </td>

      <td>
        Username
      </td>
    </tr>

    <tr>
      <td>
        Attributes
      </td>

      <td>
        Array
      </td>

      <td>
        An array of available LDAP attributes for the user's entry, including any custom attributes for the user.
      </td>
    </tr>

    <tr>
      <td>
        Groups
      </td>

      <td>
        Array
      </td>

      <td>
        Array of groups that the user belongs to.  Each group contains group's DN and a list of its LDAP attributes.
      </td>
    </tr>
  </tbody>
</Table>

### Example

Note that the response JSON has been prettified for easier reading.

```curl
{
	"DN": "cn=Test User,ou=users,dc=replicated,dc=com",
	"Username": "testuser",
	"Groups": [{
		"DN": "cn=replicated,ou=groups,dc=replicated,dc=com",
		"ID": "501",
		"Name": "replicated",
		"Attributes": {
			"cn": ["replicated"],
			"gidnumber": ["501"],
			"memberuid": ["testuser", "testuser2", "testuser3", "testuser4"],
			"objectclass": ["posixGroup", "top"]
		}
	}],
	"Attributes": {
		"cn": ["Test User"],
		"gidnumber": ["500"],
		"givenname": ["Test"],
		"homedirectory": ["/home/users/testuser"],
		"objectclass": ["inetOrgPerson", "posixAccount", "top"],
		"sn": ["User"],
		"uid": ["testuser"],
		"uidnumber": ["1005"]
	}
}
```

## /identity/v1/user/:username

Returns properties for the specified user.

### Response Status code

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>

      </th>

      <th>

      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        200
      </td>

      <td>
        User authenticated successfully
      </td>
    </tr>

    <tr>
      <td>
        401
      </td>

      <td>
        Invalid username or password (for LDAP search user)
      </td>
    </tr>

    <tr>
      <td>
        404
      </td>

      <td>
        Requested user is not found
      </td>
    </tr>
  </tbody>
</Table>

In case `200` is returned, the body of the response is the same as that of the `/identity/v1/login` call.

## /identity/v1/user/:username/exists

Checks if the supplied `username` exists on the server and returns `true` or `false`.

In case `200` is returned, the body of the response will be `true` if the user exists or `false` otherwise.

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Status
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        200
      </td>

      <td>
        Check completed successfully
      </td>
    </tr>

    <tr>
      <td>
        401
      </td>

      <td>
        Invalid username or password
      </td>
    </tr>
  </tbody>
</Table>

### Examples

```curl
$ curl -k -i $REPLICATED_INTEGRATIONAPI/identity/v1/user/jdoe/exists
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Wed, 14 Oct 2015 19:00:30 GMT
Content-Length: 4

true
```

```curl
$ curl -k -i $REPLICATED_INTEGRATIONAPI/identity/v1/user/badusername/exists
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Wed, 14 Oct 2015 19:00:30 GMT
Content-Length: 5

false
```