# GitHub auth method (API) This is the API documentation for the Vault GitHub auth method. For general information about the usage and operation of the GitHub method, please see the Vault GitHub method documentation. This documentation assumes the GitHub method is enabled at the `/auth/github` path in Vault. Since it is possible to enable auth methods at any location, please update your API calls accordingly. ### Configure method Configures the connection parameters for GitHub. This path honors the distinction between the `create` and `update` capabilities inside ACL policies. | Method | Path | | ------ | --------------------- | | `POST` | `/auth/github/config` | #### Parameters * `organization` `(string: )` - The organization users must be part of. * `organization_id` `(int: 0)` - The ID of the organization users must be part of. Vault will attempt to fetch and set this value if it is not provided. * `base_url` `(string: "")` - The API endpoint to use. Useful if you are running GitHub Enterprise or an API-compatible authentication server. #### Environment variables * `VAULT_AUTH_CONFIG_GITHUB_TOKEN` `(string: "")` - An optional GitHub token used to make authenticated GitHub API requests. This can be useful for bypassing GitHub's rate-limiting during automation flows when the `organization_id` is not provided. We encourage you to provide the `organization_id` instead of relying on this environment variable. @include 'tokenfields.mdx' #### Sample payload ```json { "organization": "acme-org" } ``` #### Sample request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/auth/github/config ``` ### Read configuration Reads the GitHub configuration. | Method | Path | | ------ | --------------------- | | `GET` | `/auth/github/config` | #### Sample request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/auth/github/config ``` #### Sample response ```json { "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6", "lease_id": "", "lease_duration": 0, "renewable": false, "data": { "organization": "acme-org", "base_url": "", "ttl": "", "max_ttl": "" }, "warnings": null } ``` ### Map GitHub teams Map a list of policies to a team that exists in the configured GitHub organization. | Method | Path | | ------ | ----------------------------------- | | `POST` | `/auth/github/map/teams/:team_name` | #### Parameters * `team_name` `(string)` - GitHub team name in "slugified" format * `value` `(string)` - Comma separated list of policies to assign #### Sample payload ```json { "value": "dev-policy" } ``` #### Sample request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/auth/github/map/teams/dev ``` ### Read team mapping Reads the GitHub team policy mapping. | Method | Path | | ------ | ----------------------------------- | | `GET` | `/auth/github/map/teams/:team_name` | #### Sample request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/auth/github/map/teams/dev ``` #### Sample response ```json { "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6", "lease_id": "", "renewable": false, "lease_duration": 0, "data": { "key": "dev", "value": "dev-policy" }, "wrap_info": null, "warnings": null, "auth": null } ``` ### Map GitHub users Map a list of policies to a specific GitHub user exists in the configured organization. | Method | Path | | ------ | ----------------------------------- | | `POST` | `/auth/github/map/users/:user_name` | #### Parameters * `user_name` `(string)` - GitHub user name * `value` `(string)` - Comma separated list of policies to assign #### Sample payload ```json { "value": "sethvargo-policy" } ``` #### Sample request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ --request POST \ --data @payload.json \ http://127.0.0.1:8200/v1/auth/github/map/users/sethvargo ``` The user with username `sethvargo` will be assigned the `sethvargo-policy` policy **in addition to** any team policies. ### Read user mapping Reads the GitHub user policy mapping. | Method | Path | | ------ | ----------------------------------- | | `GET` | `/auth/github/map/users/:user_name` | #### Sample request ```shell-session $ curl \ --header "X-Vault-Token: ..." \ http://127.0.0.1:8200/v1/auth/github/map/users/sethvargo ``` #### Sample response ```json { "request_id": "764b6f88-efba-51bd-ed62-cf1c9e80e37a", "lease_id": "", "renewable": false, "lease_duration": 0, "data": { "key": "sethvargo", "value": "sethvargo-policy" }, "wrap_info": null, "warnings": null, "auth": null } ``` ### Login Login using GitHub access token. | Method | Path | | ------ | -------------------- | | `POST` | `/auth/github/login` | #### Parameters * `token` `(string: )` - GitHub personal API token. #### Sample payload ```json { "token": "ABC123..." } ``` #### Sample request ```shell-session $ curl \ --request POST \ http://127.0.0.1:8200/v1/auth/github/login ``` #### Sample response ```javascript { "lease_id": "", "renewable": false, "lease_duration": 0, "data": null, "warnings": null, "auth": { "client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344", "accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d", "policies": ["default"], "metadata": { "username": "fred", "org": "acme-org" }, }, "lease_duration": 7200, "renewable": true } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.enclaive.cloud/vault/api/auth-engines/github-auth-method-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.