# Create an installation access token for an app

From **GitHub v3 REST API**.

`POST /app/installations/{installation_id}/access_tokens`

Creates an installation access token that enables a GitHub App to make authenticated API requests for the app's installation on an organization or individual account. Installation tokens expire one hour from the time you create them. Using an expired token produces a status code of `401 - Unauthorized`, and requires creating a new installation token. By default the installation token has access to all repositories that the installation can access. To restrict the access to specific repositories, you can provide the `repository_ids` when creating the token. When you omit `repository_ids`, the response does not contain the `repositories` key.

You must use a [JWT](https://docs.github.com/enterprise-server@3.0/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint.

## Parameters

### `installation_id`

- Location: path
- Required: true
- Type: `integer`

installation_id parameter

## Request body

- Required: false
### `application/json`

- Type: `object`

```json
{"properties":{"permissions":{"$ref":"#/components/schemas/app-permissions"},"repositories":{"description":"List of repository names that the token should have access to","items":{"example":"rails","type":"string"},"type":"array"},"repository_ids":{"description":"List of repository IDs that the token should have access to","example":[1],"items":{"type":"integer"},"type":"array"}},"type":"object"}
```

## Responses

### `201`

Response

### `application/json`

- Type: `object`

Authentication token for a GitHub App installed on a user or org.

```json
{
  "expires_at": "2016-07-11T22:14:10Z",
  "permissions": {
    "contents": "read",
    "issues": "write"
  },
  "repositories": [
    {
      "allow_merge_commit": true,
      "allow_rebase_merge": true,
      "allow_squash_merge": true,
      "archive_url": "https://api.github.com/repos/octocat/Hello-World/{archive_format}{/ref}",
      "archived": false,
      "assignees_url": "https://api.github.com/repos/octocat/Hello-World/assignees{/user}",
      "blobs_url": "https://api.github.com/repos/octocat/Hello-World/git/blobs{/sha}",
      "branches_url": "https://api.github.com/repos/octocat/Hello-World/branches{/branch}",
      "clone_url": "https://github.com/octocat/Hello-World.git",
      "collaborators_url": "https://api.github.com/repos/octocat/Hello-World/collaborators{/collaborator}",
      "comments_url": "https://api.github.com/repos/octocat/Hello-World/comments{/number}",
      "commits_url": "https://api.github.com/repos/octocat/Hello-World/commits{/sha}",
      "compare_url": "https://api.github.com/repos/octocat/Hello-World/compare/{base}...{head}",
      "contents_url": "https://api.github.com/repos/octocat/Hello-World/contents/{+path}",
      "contributors_url": "https://api.github.com/repos/octocat/Hello-World/contributors",
      "created_at": "2011-01-26T19:01:12Z",
      "default_branch": "master",
      "delete_branch_on_merge": true,
      "deployments_url": "https://api.github.com/repos/octocat/Hello-World/deployments",
      "description": "This your first repo!",
      "disabled": false,
      "downloads_url": "https://api.github.com/repos/octocat/Hello-World/downloads",
      "events_url": "https://api.github.com/repos/octocat/Hello-World/events",
      "fork": false,
      "forks": 1,
      "forks_count": 9,
      "forks_url": "https://api.github.com/repos/octocat/Hello-World/forks",
      "full_name": "octocat/Hello-World",
      "git_commits_url": "https://api.github.com/repos/octocat/Hello-World/git/commits{/sha}",
      "git_refs_url": "https://api.github.com/repos/octocat/Hello-World/git/refs{/sha}",
      "git_tags_url": "https://api.github.com/repos/octocat/Hello-World/git/tags{/sha}",
      "git_url": "git:github.com/octocat/Hello-World.git",
      "has_downloads": true,
      "has_issues": true,
      "has_pages": false,
      "has_projects": true,
      "has_wiki": true,
      "homepage": "https://github.com",
      "hooks_url": "https://api.github.com/repos/octocat/Hello-World/hooks",
      "html_url": "https://github.com/octocat/Hello-World",
      "id": 1296269,
      "is_template": true,
      "issue_comment_url": "https://api.github.com/repos/octocat/Hello-World/issues/comments{/number}",
      "issue_events_url": "https://api.github.com/repos/octocat/Hello-World/issues/events{/number}",
      "issues_url": "https://api.github.com/repos/octocat/Hello-World/issues{/number}",
      "keys_url": "https://api.github.com/repos/octocat/Hello-World/keys{/key_id}",
      "labels_url": "https://api.github.com/repos/octocat/Hello-World/labels{/name}",
      "language": null,
      "languages_url": "https://api.github.com/repos/octocat/Hello-World/languages",
      "license": {
        "html_url": "https://github.com/licenses/mit",
        "key": "mit",
        "name": "MIT License",
        "node_id": "MDc6TGljZW5zZW1pdA==",
        "spdx_id": "MIT",
        "url": "https://api.github.com/licenses/mit"
      },
      "merges_url": "https://api.github.com/repos/octocat/Hello-World/merges",
      "milestones_url": "https://api.github.com/repos/octocat/Hello-World/milestones{/number}",
      "mirror_url": "git:git.example.com/octocat/Hello-World",
      "name": "Hello-World",
      "network_count": 0,
      "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
      "notifications_url": "https://api.github.com/repos/octocat/Hello-World/notifications{?since,all,participating}",
      "open_issues": 1,
      "open_issues_count": 0,
      "owner": {
        "avatar_url": "https://github.com/images/error/octocat_happy.gif",
        "events_url": "https://api.github.com/users/octocat/events{/privacy}",
        "followers_url": "https://api.github.com/users/octocat/followers",
        "following_url": "https://api.github.com/users/octocat/following{/other_user}",
        "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
        "gravatar_id": "",
        "html_url": "https://github.com/octocat",
        "id": 1,
        "login": "octocat",
        "node_id": "MDQ6VXNlcjE=",
        "organizations_url": "https://api.github.com/users/octocat/orgs",
        "received_events_url": "https://api.github.com/users/octocat/received_events",
        "repos_url": "https://api.github.com/users/octocat/repos",
        "site_admin": false,
        "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
        "type": "User",
        "url": "https://api.github.com/users/octocat"
      },
      "permissions": {
        "admin": false,
        "pull": true,
        "push": false
      },
      "private": false,
      "pulls_url": "https://api.github.com/repos/octocat/Hello-World/pulls{/number}",
      "pushed_at": "2011-01-26T19:06:43Z",
      "releases_url": "https://api.github.com/repos/octocat/Hello-World/releases{/id}",
      "size": 108,
      "ssh_url": "git@github.com:octocat/Hello-World.git",
      "stargazers_count": 80,
      "stargazers_url": "https://api.github.com/repos/octocat/Hello-World/stargazers",
      "statuses_url": "https://api.github.com/repos/octocat/Hello-World/statuses/{sha}",
      "subscribers_count": 42,
      "subscribers_url": "https://api.github.com/repos/octocat/Hello-World/subscribers",
      "subscription_url": "https://api.github.com/repos/octocat/Hello-World/subscription",
      "svn_url": "https://svn.github.com/octocat/Hello-World",
      "tags_url": "https://api.github.com/repos/octocat/Hello-World/tags",
      "teams_url": "https://api.github.com/repos/octocat/Hello-World/teams",
      "temp_clone_token": "ABTLWHOULUVAXGTRYU7OC2876QJ2O",
      "template_repository": null,
      "topics": [
        "octocat",
        "atom",
        "electron",
        "api"
      ],
      "trees_url": "https://api.github.com/repos/octocat/Hello-World/git/trees{/sha}",
      "updated_at": "2011-01-26T19:14:43Z",
      "url": "https://api.github.com/repos/octocat/Hello-World",
      "visibility": "public",
      "watchers": 1,
      "watchers_count": 80
    }
  ],
  "repository_selection": "selected",
  "token": "ghs_16C7e42F292c6912E7710c838347Ae178B4a"
}
```

```json
{"description":"Authentication token for a GitHub App installed on a user or org.","properties":{"expires_at":{"type":"string"},"has_multiple_single_files":{"example":true,"type":"boolean"},"permissions":{"$ref":"#/components/schemas/app-permissions"},"repositories":{"items":{"$ref":"#/components/schemas/repository"},"type":"array"},"repository_selection":{"enum":["all","selected"],"type":"string"},"single_file":{"example":"README.md","type":"string"},"single_file_paths":{"example":["config.yml",".github/issue_TEMPLATE.md"],"items":{"type":"string"},"type":"array"},"token":{"type":"string"}},"required":["token","expires_at"],"title":"Installation Token","type":"object"}
```

### `401`

Requires authentication

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `403`

Forbidden

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `404`

Resource not found

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `415`

Preview header missing

### `application/json`

- Type: `object`

```json
{"properties":{"documentation_url":{"type":"string"},"message":{"type":"string"}},"required":["message","documentation_url"],"type":"object"}
```

### `422`

Validation failed

### `application/json`

- Type: `object`

Validation Error

```json
{"description":"Validation Error","properties":{"documentation_url":{"type":"string"},"errors":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"index":{"type":"integer"},"message":{"type":"string"},"resource":{"type":"string"},"value":{"oneOf":[{"nullable":true,"type":"string"},{"nullable":true,"type":"integer"},{"items":{"type":"string"},"nullable":true,"type":"array"}]}},"required":["code"],"type":"object"},"type":"array"},"message":{"type":"string"}},"required":["message","documentation_url"],"title":"Validation Error","type":"object"}
```

## Request examples

### cURL

```shell
curl --request POST \
  --url {protocol}://{hostname}/api/v3/app/installations/{installation_id}/access_tokens \
  --header 'content-type: application/json' \
  --data '{
  "permissions": {
    "actions": "string",
    "administration": "string",
    "checks": "string",
    "content_references": "string",
    "contents": "string",
    "deployments": "string",
    "environments": "string",
    "issues": "string",
    "members": "string",
    "metadata": "string",
    "organization_administration": "string",
    "organization_hooks": "string",
    "organization_packages": "string",
    "organization_plan": "string",
    "organization_projects": "string",
    "organization_secrets": "string",
    "organization_self_hosted_runners": "string",
    "organization_user_blocking": "string",
    "packages": "string",
    "pages": "string",
    "pull_requests": "string",
    "repository_hooks": "string",
    "repository_projects": "string",
    "secret_scanning_alerts": "string",
    "secrets": "string",
    "security_events": "string",
    "single_file": "string",
    "statuses": "string",
    "team_discussions": "string",
    "vulnerability_alerts": "string",
    "workflows": "string"
  },
  "repositories": [
    "string"
  ],
  "repository_ids": [
    1
  ]
}'
```