gloak

Core types and HTTP helpers for the gloak Keycloak library.

This module owns validated boundary values and the shared Sans-IO request and response helpers used by gloak/oidc and gloak/admin. It does not send HTTP requests, manage processes, store tokens, or verify JWT signatures. Callers execute the returned gleam_http requests with their HTTP client of choice and pass responses back to *_response functions.

Examples

import gloak

pub fn build_server() {
  gloak.server("https://auth.example.com")
}

Types

AccessToken

opaque

@superdocs Core Values Bearer access token.

pub opaque type AccessToken

ClientId

opaque

@superdocs Core Values OAuth client id.

pub opaque type ClientId

ClientSecret

opaque

@superdocs Core Values OAuth client secret. Keep this value server-side.

pub opaque type ClientSecret

ClientUuid

opaque

@superdocs Core Values Keycloak internal client UUID.

pub opaque type ClientUuid

EmailVerification

@superdocs Domain States Whether Keycloak considers an email address verified.

pub type EmailVerification {
  EmailAddressVerified
  EmailAddressUnverified
}

Constructors

```
EmailAddressVerified
```
```
EmailAddressUnverified
```

Error

@superdocs Errors Library errors for configuration, request construction, and response decode.

pub type Error {
  InvalidConfiguration(field: String, reason: String)
  InvalidRequestUrl(url: String)
  UnexpectedStatus(status: Int, body: String)
  InvalidResponseBody(reason: String)
  MissingHeader(name: String)
  InvalidCallback(reason: String)
  VerificationFailed(reason: String)
}

Constructors

```
InvalidConfiguration(field: String, reason: String)
```
A caller-provided configuration or domain value is invalid.
```
InvalidRequestUrl(url: String)
```
A request could not be built from a URL in configuration or metadata.

UnexpectedStatus(status: Int, body: String)

Keycloak returned a non-2xx HTTP status.

```
InvalidResponseBody(reason: String)
```
A response body could not be decoded as the expected contract.
```
MissingHeader(name: String)
```
A required response header was absent.
```
InvalidCallback(reason: String)
```
An authorization callback failed validation.
```
VerificationFailed(reason: String)
```
JWT verification or verified-claim decoding failed.

ExpirationRequirement

@superdocs Domain States Whether JWT validation requires an expiration claim.

pub type ExpirationRequirement {
  RequireExpiration
  AllowMissingExpiration
}

Constructors

```
RequireExpiration
```
```
AllowMissingExpiration
```

GroupId

opaque

@superdocs Core Values Keycloak group id.

pub opaque type GroupId

IdToken

opaque

@superdocs Core Values OIDC ID token.

pub opaque type IdToken

KeycloakRequest

@superdocs HTTP Boundary The request type returned by every *_request function.

pub type KeycloakRequest =
  request.Request(String)

KeycloakResponse

@superdocs HTTP Boundary The response type accepted by every *_response function.

pub type KeycloakResponse =
  response.Response(String)

PasswordCredentialState

@superdocs Domain States Password reset credential lifecycle.

pub type PasswordCredentialState {
  TemporaryPassword
  PermanentPassword
}

Constructors

```
TemporaryPassword
```
```
PermanentPassword
```

Realm

opaque

@superdocs Core Values Keycloak realm name.

pub opaque type Realm

RefreshToken

opaque

@superdocs Core Values OAuth refresh token.

pub opaque type RefreshToken

ResourceState

@superdocs Domain States Administrative resource lifecycle state.

pub type ResourceState {
  ResourceEnabled
  ResourceDisabled
}

Constructors

```
ResourceEnabled
```
```
ResourceDisabled
```

RoleOrigin

@superdocs Domain States Source of an Admin API role.

pub type RoleOrigin {
  RealmRole
  ClientRole
}

Constructors

```
RealmRole
```
```
ClientRole
```

Server

opaque

@superdocs Core Values Keycloak server origin, without a trailing slash.

pub opaque type Server

TokenActivity

@superdocs Domain States OAuth token activity returned by introspection.

pub type TokenActivity {
  TokenActive
  TokenInactive
}

Constructors

```
TokenActive
```
```
TokenInactive
```

UserId

opaque

@superdocs Core Values Keycloak user id.

pub opaque type UserId

Values

access_token

pub fn access_token(value: String) -> Result(AccessToken, Error)

@superdocs Constructors Builds a non-empty access token.

access_token_to_string

pub fn access_token_to_string(value: AccessToken) -> String

@superdocs Conversions Returns the access token string.

bearer_header

pub fn bearer_header(token: AccessToken) -> #(String, String)

@superdocs HTTP Boundary Header for bearer-token authenticated requests.

client_id

pub fn client_id(value: String) -> Result(ClientId, Error)

@superdocs Constructors Builds a non-empty client id.

client_id_to_string

pub fn client_id_to_string(value: ClientId) -> String

@superdocs Conversions Returns the client id string.

client_secret

pub fn client_secret(
  value: String,
) -> Result(ClientSecret, Error)

@superdocs Constructors Builds a non-empty client secret.

client_secret_to_string

pub fn client_secret_to_string(value: ClientSecret) -> String

@superdocs Conversions Returns the client secret string.

client_uuid

pub fn client_uuid(value: String) -> Result(ClientUuid, Error)

@superdocs Constructors Builds a non-empty Keycloak internal client UUID.

client_uuid_to_string

pub fn client_uuid_to_string(value: ClientUuid) -> String

@superdocs Conversions Returns the client UUID string.

created_location_response

pub fn created_location_response(
  response: response.Response(String),
) -> Result(String, Error)

@superdocs HTTP Boundary Decodes a 201 Created response location header.

decode_json_response

pub fn decode_json_response(
  response: response.Response(String),
  decoder: decode.Decoder(a),
) -> Result(a, Error)

@superdocs HTTP Boundary Decodes a successful JSON response body with a dynamic decoder.

form_body

pub fn form_body(values: List(#(String, String))) -> String

@superdocs HTTP Boundary Builds an application/x-www-form-urlencoded request body.

form_headers

pub fn form_headers() -> List(#(String, String))

@superdocs HTTP Boundary Header for form-url-encoded OAuth requests.

group_id

pub fn group_id(value: String) -> Result(GroupId, Error)

@superdocs Constructors Builds a non-empty group id.

group_id_to_string

pub fn group_id_to_string(value: GroupId) -> String

@superdocs Conversions Returns the group id string.

id_token

pub fn id_token(value: String) -> Result(IdToken, Error)

@superdocs Constructors Builds a non-empty ID token.

id_token_to_string

pub fn id_token_to_string(value: IdToken) -> String

@superdocs Conversions Returns the ID token string.

json_headers

pub fn json_headers() -> List(#(String, String))

@superdocs HTTP Boundary Header for JSON request and response bodies.

realm

pub fn realm(value: String) -> Result(Realm, Error)

@superdocs Constructors Builds a non-empty realm name.

realm_to_string

pub fn realm_to_string(value: Realm) -> String

@superdocs Conversions Returns the realm name string.

refresh_token

pub fn refresh_token(
  value: String,
) -> Result(RefreshToken, Error)

@superdocs Constructors Builds a non-empty refresh token.

refresh_token_to_string

pub fn refresh_token_to_string(value: RefreshToken) -> String

@superdocs Conversions Returns the refresh token string.

request

pub fn request(
  server server: Server,
  method method: http.Method,
  path path: String,
  query query: List(#(String, String)),
  headers headers: List(#(String, String)),
  body body: String,
) -> request.Request(String)

@superdocs HTTP Boundary Builds a request relative to the validated Keycloak server origin.

request_to

pub fn request_to(
  url url: String,
  method method: http.Method,
  headers headers: List(#(String, String)),
  body body: String,
) -> Result(request.Request(String), Error)

@superdocs HTTP Boundary Builds a request from an absolute URL, usually from discovered OIDC metadata.

server

pub fn server(value: String) -> Result(Server, Error)

@superdocs Constructors Builds a Keycloak server origin from http:// or https:// input.

gloak.server("https://auth.example.com/")
// -> Ok(server)

server_to_string

pub fn server_to_string(value: Server) -> String

@superdocs Conversions Returns the server origin string.

success_response

pub fn success_response(
  response: response.Response(String),
) -> Result(response.Response(String), Error)

@superdocs HTTP Boundary Returns Ok(response) for 2xx statuses or an UnexpectedStatus error.

user_id

pub fn user_id(value: String) -> Result(UserId, Error)

@superdocs Constructors Builds a non-empty user id.

user_id_to_string

pub fn user_id_to_string(value: UserId) -> String

@superdocs Conversions Returns the user id string.