# `mix hex.organization`
[🔗](https://github.com/hexpm/hex/blob/v2.6.0/lib/mix/tasks/hex.organization.ex#L1)

Manages the list of authorized Hex.pm organizations.

Organizations is a feature of Hex.pm to host and manage private packages. See
<https://hex.pm/docs/private> for more information.

By default you will be authorized to all your organizations when running
`mix hex.user auth` and this is the recommended approach for development. This
task is mainly provided for CI and build systems where access to an organization
is needed without authorizing a user.

For CI, generate an organization key with `mix hex.organization key ORGANIZATION generate`
and authenticate with it right before fetching dependencies. Hex exchanges the key
for a short-lived token and stores only the token:

    mix hex.organization auth ORGANIZATION --key KEY

A GitHub Actions job with the `id-token: write` permission can fetch the
organization's packages without a key, using Workload Identity, sometimes also
known as "Trusted Publishing". Configure a workload identity with the `read`
or `write` role for the organization on hex.pm. When there's no token from
`mix hex.organization auth --key` and no authenticated user, Hex exchanges the
job's OIDC token for a short-lived token that can fetch the organization's
packages.

To use a package from an organization add `organization: "my_organization"` to the
dependency declaration in `mix.exs`:

    {:plug, "~> 1.0", organization: "my_organization"}

## Authorize an organization

Exchanges an organization key for a short-lived token used to fetch the
organization's packages. Hex uses the token for about 25 minutes and doesn't
refresh it, so in CI run this command right before fetching dependencies. For
development use `mix hex.user auth` instead.

    $ mix hex.organization auth ORGANIZATION --key KEY

## Deauthorize and remove an organization

    $ mix hex.organization deauth NAME

## List all authorized organizations

This command will only list organizations you have authorized with this task, it will not
list organizations you have access to by having authorized with `mix hex.user auth`.

    $ mix hex.organization list

## Generate organization key

This command is useful to pre-generate keys for use with `mix hex.organization auth ORGANIZATION --key KEY`
on CI servers or similar systems. It returns the hash of the generated key that you can pass to
`auth ORGANIZATION --key KEY`. Unlike the `hex.user key` commands, a key generated with this
command is owned by the organization directly, and not the user that generated it. This makes it
ideal for shared environments such as CI where you don't want to give access to user-specific
resources and the user's organization membership status won't affect key. By default this command
sets the `repository:organization_name` permission which allows read-only access to the organization's repository, it can be
overridden with the `--permission` flag.

    $ mix hex.organization key ORGANIZATION generate [--key-name KEY_NAME] [--permission PERMISSION]

## Revoke key

Removes given key from organization.

The key can no longer be used to authenticate API requests.

    $ mix hex.organization key ORGANIZATION revoke KEY_NAME

## Revoke all keys

Revoke all keys from the organization.

    $ mix hex.organization key ORGANIZATION revoke --all

## List keys

Lists all keys associated with the organization.

    $ mix hex.organization key ORGANIZATION list

## Command line options

  * `--key KEY` - Required for `auth`. An organization key, generated with
    `mix hex.organization key ORGANIZATION generate`, that is exchanged for a
    short-lived token

  * `--key-name KEY_NAME` - The name of the key created by `key generate`. By
    default Hex bases the key name on your machine's hostname.

  * `--permission PERMISSION` - Sets the permissions on the key, this option can be given
    multiple times, possibly values are:
    * `api:read` - API read access.
    * `api:write` - API write access.
    * `repository:organization_name` - Access to the organization's repository (this is the default permission).

---

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