# Java types

The Java SDK provides credential classes, enums, and helper types for authentication and data operations.

The SDK provides several supporting types for authentication, update operations, and relation modelling. These types are used as parameters to methods on the [`Surreal`](/docs/reference/java/api/core/surreal.md) class.

**Source:** [surrealdb.java](https://github.com/surrealdb/surrealdb.java)

---

## Authentication types

### `Credential` {#credential}

Interface. Base type for all credentials passed to [`signin()`](/docs/reference/java/api/core/surreal.md#signin) and [`signup()`](/docs/reference/java/api/core/surreal.md#signup).

### `Signin` {#signin}

Interface. Extends `Credential`. Marker interface for sign-in credentials.

---

### `RootCredential` {#root-credential}

Implements `Signin`. Authenticates as a root user.

```java title="Constructor"
RootCredential(String username, String password)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>username</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The root username.</td>
        </tr>
        <tr>
            <td><code>password</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The root password.</td>
        </tr>
    </tbody>
</table>

#### Methods

| Method | Returns | Description |
|---|---|---|
| `.getUsername()` | `String` | The root username |
| `.getPassword()` | `String` | The root password |

```java title="Example"
db.signin(new RootCredential("root", "root"));
```

---

### `NamespaceCredential` {#namespace-credential}

Extends `RootCredential`. Authenticates as a namespace user.

```java title="Constructor"
NamespaceCredential(String username, String password, String namespace)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>username</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The namespace username.</td>
        </tr>
        <tr>
            <td><code>password</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The namespace password.</td>
        </tr>
        <tr>
            <td><code>namespace</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The namespace to authenticate against.</td>
        </tr>
    </tbody>
</table>

#### Additional method

| Method | Returns | Description |
|---|---|---|
| `.getNamespace()` | `String` | The target namespace |

```java title="Example"
db.signin(new NamespaceCredential("ns_user", "ns_pass", "surrealdb"));
```

---

### `DatabaseCredential` {#database-credential}

Extends `NamespaceCredential`. Authenticates as a database user.

```java title="Constructor"
DatabaseCredential(String username, String password, String namespace, String database)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>username</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The database username.</td>
        </tr>
        <tr>
            <td><code>password</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The database password.</td>
        </tr>
        <tr>
            <td><code>namespace</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The namespace containing the database.</td>
        </tr>
        <tr>
            <td><code>database</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The database to authenticate against.</td>
        </tr>
    </tbody>
</table>

#### Additional method

| Method | Returns | Description |
|---|---|---|
| `.getDatabase()` | `String` | The target database |

```java title="Example"
db.signin(new DatabaseCredential("db_user", "db_pass", "surrealdb", "docs"));
```

---

### `RecordCredential` {#record-credential}

Implements `Credential`. Authenticates as a record user via an access method defined with [`DEFINE ACCESS`](/docs/reference/query-language/statements/define/access.md).

```java title="Constructors"
RecordCredential(String namespace, String database, String access, Object params)
RecordCredential(String access, Object params)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>namespace</code> _(optional)_</td>
            <td><code>String</code></td>
            <td>The namespace. Omit to use the session namespace.</td>
        </tr>
        <tr>
            <td><code>database</code> _(optional)_</td>
            <td><code>String</code></td>
            <td>The database. Omit to use the session database.</td>
        </tr>
        <tr>
            <td><code>access</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The access method name.</td>
        </tr>
        <tr>
            <td><code>params</code> _(required)_</td>
            <td><code>Object</code></td>
            <td>Additional fields required by the access definition.</td>
        </tr>
    </tbody>
</table>

#### Methods

| Method | Returns | Description |
|---|---|---|
| `.getNamespace()` | `String` | The target namespace |
| `.getDatabase()` | `String` | The target database |
| `.getAccess()` | `String` | The access method name |
| `.getParams()` | `Object` | The additional parameters |

```java title="Example"
Token token = db.signup(new RecordCredential(
    "surrealdb", "docs", "user_access",
    Map.of("email", "user@example.com", "password", "s3cret")
));
```

---

### `BearerCredential` {#bearer-credential}

Implements `Credential`. Authenticates with an existing token.

```java title="Constructor"
BearerCredential(String token)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>token</code> _(required)_</td>
            <td><code>String</code></td>
            <td>A valid JWT token string.</td>
        </tr>
    </tbody>
</table>

#### Method

| Method | Returns | Description |
|---|---|---|
| `.getToken()` | `String` | The bearer token |

```java title="Example"
db.signin(new BearerCredential("eyJhbGciOiJIUzI1NiIs..."));
```

---

### `Token` {#token}

Represents authentication tokens returned by [`signin()`](/docs/reference/java/api/core/surreal.md#signin) and [`signup()`](/docs/reference/java/api/core/surreal.md#signup).

```java title="Constructors"
Token(String access, String refresh)
Token(String token)
```

<table>
    <thead>
        <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Description</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><code>access</code> _(required)_</td>
            <td><code>String</code></td>
            <td>The access token (JWT).</td>
        </tr>
        <tr>
            <td><code>refresh</code> _(optional)_</td>
            <td><code>String</code></td>
            <td>The refresh token. May be <code>null</code>.</td>
        </tr>
        <tr>
            <td><code>token</code> _(required)_</td>
            <td><code>String</code></td>
            <td>A single token string (legacy constructor).</td>
        </tr>
    </tbody>
</table>

#### Methods

| Method | Returns | Description |
|---|---|---|
| `.getAccess()` | `String` | The access token (JWT) |
| `.getRefresh()` | `String` | The refresh token (may be `null`) |
| `.getToken()` | `String` | The access token |

```java title="Example"
Token token = db.signin(new RootCredential("root", "root"));
String jwt = token.getAccess();
String refresh = token.getRefresh();
```

---

## Operation types

### `UpType` {#up-type}

Enum for [`update()`](/docs/reference/java/api/core/surreal.md#update) and [`upsert()`](/docs/reference/java/api/core/surreal.md#upsert) operation types.

| Value | Description |
|---|---|
| `CONTENT` | Replaces the entire record content |
| `MERGE` | Merges fields with the existing record |
| `PATCH` | Applies partial changes |

```java title="Example"
db.update(Person.class, new RecordId("person", "alice"), UpType.MERGE, updates);
```

---

## Relation types

### `Relation` {#relation}

POJO base class for graph relations. Contains the standard relation fields. Used with [`relate()`](/docs/reference/java/api/core/surreal.md#relate).

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | `RecordId` | The relation record ID |
| `in` | `RecordId` | The source record |
| `out` | `RecordId` | The target record |

```java title="Example"
public class Likes extends Relation {
    public String createdAt;
}

Likes like = db.relate(Likes.class,
    new RecordId("person", "alice"),
    "likes",
    new RecordId("post", "post1")
);
```

---

### `InsertRelation` {#insert-relation}

POJO for inserting relations. Uses `Id` instead of `RecordId` for the `id` field. Used with [`insertRelation()`](/docs/reference/java/api/core/surreal.md#insert-relation).

#### Fields

| Field | Type | Description |
|---|---|---|
| `id` | `Id` | The relation ID |
| `in` | `RecordId` | The source record |
| `out` | `RecordId` | The target record |

```java title="Example"
public class Likes extends InsertRelation {
    public String createdAt;
}

Likes like = new Likes();
like.in = new RecordId("person", "alice");
like.out = new RecordId("post", "post1");
like.createdAt = "2025-01-01T00:00:00Z";

Likes result = db.insertRelation(Likes.class, "likes", like);
```

---

## Utility types

### `NsDb` {#ns-db}

Holds a namespace and database pair.

#### Methods

| Method | Returns | Description |
|---|---|---|
| `.getNamespace()` | `String` | The namespace |
| `.getDatabase()` | `String` | The database |

---

## See also

- [Surreal](/docs/reference/java/api/core/surreal.md) - Connection and method reference
- [Authentication](/docs/reference/java/concepts/authentication.md) - Authentication concepts and patterns
- [Data manipulation](/docs/reference/java/concepts/data-manipulation.md) - CRUD operation patterns
- [DEFINE USER](/docs/reference/query-language/statements/define/user.md) - System user definition for root, namespace, and database credentials
- [DEFINE ACCESS](/docs/reference/query-language/statements/define/access.md) - Access method definition for record-level authentication