# `Ltix.Registration`
[🔗](https://github.com/DecoyLex/ltix/blob/main/lib/ltix/registration.ex#L1)

Everything the tool stores about a registered platform, established
out-of-band before any launch occurs.

A registration contains the values exchanged during out-of-band setup
between the tool and platform. Multiple deployments on a given platform
may share the same `client_id`.

## Fields

  * `:issuer` - HTTPS URL identifying the platform (no query or fragment)
  * `:client_id` - OAuth client ID assigned by the platform
  * `:auth_endpoint` - HTTPS URL for the OIDC authorization endpoint
  * `:jwks_uri` - HTTPS URL where the platform publishes its public keys
  * `:token_endpoint` - HTTPS URL for OAuth token requests (required for
    Advantage services, `nil` if not using them)
  * `:audience` - the audience the platform expects in token requests,
    when it gives you one that differs from the token endpoint. Defaults
    to the token endpoint.

## Examples

    {:ok, reg} = Ltix.Registration.new(%{
      issuer: "https://canvas.example.edu",
      client_id: "10000000000042",
      auth_endpoint: "https://canvas.example.edu/api/lti/authorize_redirect",
      jwks_uri: "https://canvas.example.edu/api/lti/security/jwks",
      token_endpoint: "https://canvas.example.edu/login/oauth2/token"
    })

# `t`

```elixir
@type t() :: %Ltix.Registration{
  audience: String.t() | nil,
  auth_endpoint: String.t(),
  client_id: String.t(),
  issuer: String.t(),
  jwks_uri: String.t(),
  token_endpoint: String.t() | nil
}
```

# `new`

```elixir
@spec new(keyword() | map()) :: {:ok, t()} | {:error, Exception.t()}
```

Create a new registration with validation from a keyword list or an
atom-keyed map. Unknown fields are rejected.

## Validation rules

- `issuer` - HTTPS URL with no query or fragment
- `client_id` - non-empty string
- `auth_endpoint` - HTTPS URL
- `jwks_uri` - HTTPS URL
- `token_endpoint` - HTTPS URL (when present)
- `audience` - non-empty string, and a URI if it includes a colon (when present)

HTTPS URLs must be absolute and must not include a userinfo component (RFC 3986 §3.2.1).
HTTP URLs are accepted for platforms on a loopback or local host, such as
`http://localhost:8080`.

## Examples

    iex> {:ok, reg} = Ltix.Registration.new(%{
    ...>   issuer: "https://platform.example.com",
    ...>   client_id: "tool-123",
    ...>   auth_endpoint: "https://platform.example.com/auth",
    ...>   jwks_uri: "https://platform.example.com/.well-known/jwks.json"
    ...> })
    iex> reg.issuer
    "https://platform.example.com"

# `new!`

```elixir
@spec new!(keyword() | map()) :: t()
```

Same as `new/1`, but returns the registration or raises the error.

## Examples

    iex> registration = Ltix.Registration.new!(
    ...>   issuer: "https://platform.example.com",
    ...>   client_id: "tool-123",
    ...>   auth_endpoint: "https://platform.example.com/auth",
    ...>   jwks_uri: "https://platform.example.com/.well-known/jwks.json"
    ...> )
    iex> registration.client_id
    "tool-123"

---

*Consult [api-reference.md](api-reference.md) for complete listing*