# `Ory.Connection`

Handle Tesla connections for Ory.

Additional middleware can be set in the compile-time or runtime configuration:

    config :tesla, Ory.Connection,
      base_url: "https://playground.projects.oryapis.com",
      adapter: Tesla.Adapter.Hackney

The default base URL can also be set as:

    config :ory_client,
      :base_url, "https://playground.projects.oryapis.com"

# `options`

```elixir
@type options() :: [
  base_url: String.t(),
  user_agent: String.t(),
  token: String.t() | token_fetcher(),
  token_scopes: [String.t()],
  username: String.t() | nil,
  password: String.t() | nil
]
```

The list of options that can be passed to new/1.

- `base_url`: Overrides the base URL on a per-client basis.
- `user_agent`: Overrides the User-Agent header.
- `token`: An OAuth2 token or a token fetcher function.
- `token_scopes`: A list of OAuth2 scope strings for use with a token
  fetcher function.
- `username`: A username for basic authentication.
- `password`: A password for basic authentication.

# `token_fetcher`

```elixir
@type token_fetcher() :: (scopes :: [String.t()] -> String.t()) | {module(), atom()}
```

An arity-1 function or module/function tuple specification which, given
a list of scopes, obtains an OAuth2 token.

# `adapter`

Returns the default adapter for this API.

# `authorization`

```elixir
@spec authorization(String.t() | token_fetcher(), [String.t()]) ::
  Tesla.Client.middleware()
```

Returns an authentication middleware tuple for a Tesla client that sets
the `authorization` header to the value of the provided bearer token. If
the token is provided as a function of arity one, it will be called with
a list of requested scopes that will obtain an OAuth2 token.

### Parameters

- `token`: a String or a function of arity one. This value, or the result
  of the function call, will be set as a bearer token in the
  `authorization` header.

- `scopes`: an optional list of scopes for use with the token fetcher
  function. Ignored when `token` is provided as a String. Defaults to
  `["offline", "offline_access", "openid"]`.

### Returns

`{Tesla.Middleware.Headers, [{"authorization", TOKEN}]}`

# `middleware`

```elixir
@spec middleware(options()) :: [Tesla.Client.middleware()]
```

Returns fully configured middleware for passing to Tesla.client/2.

# `new`

```elixir
@spec new() :: Tesla.Env.client()
```

Configure a client with no authentication.

### Returns

Tesla.Env.client

# `new`

```elixir
@spec new(String.t() | token_fetcher() | options()) :: Tesla.Env.client()
```

Configure a client that may have authentication.

### Parameters

The first parameter *may* be a `token` (a string, a token fetcher class,
or a module/function tuple) or a keyword list of `options`. They are
documented separately, but only *one* of them will be passed.

- `token`: a String or a function of arity one. This value, or the result
  of the function call, will be set as a bearer token in the
  `authorization` header.
- `options`: a keyword list of OpenAPIPetstore.Connection.options.

### Returns

Tesla.Env.client

# `new`

```elixir
@spec new(
  token_or_username :: String.t() | token_fetcher(),
  scopes_or_password :: [String.t()] | String.t(),
  options()
) :: Tesla.Env.client()
```

Configure a client using bearer authentication with scopes, or with
username and password for basic authentication.

### Parameters

- `token_or_username`: a String representing a bearer token or a username,
  depending on the type of the next parameter, or a function arity one
  that returns a bearer token.
- `scopes_or_password`: a list of Strings represenging OAuth2 scopes, or
  a single string that is the password for the username provided.
- `options`: a keyword list of OpenAPIPetstore.Connection.options.

### Returns

Tesla.Env.client

# `request`

```elixir
@spec request(Tesla.Client.t(), [Tesla.option()]) :: Tesla.Env.result()
```

Forward requests to Tesla.

---

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