code.gitea.io/gitea@v1.22.3/docs/content/development/api-usage.en-us.md (about)

     1  ---
     2  date: "2018-06-24:00:00+02:00"
     3  title: "API Usage"
     4  slug: "api-usage"
     5  sidebar_position: 40
     6  toc: false
     7  draft: false
     8  aliases:
     9    - /en-us/api-usage
    10  menu:
    11    sidebar:
    12      parent: "development"
    13      name: "API Usage"
    14      sidebar_position: 40
    15      identifier: "api-usage"
    16  ---
    17  
    18  # API Usage
    19  
    20  ## Enabling/configuring API access
    21  
    22  By default, `ENABLE_SWAGGER` is true, and `MAX_RESPONSE_ITEMS` is set to 50. See [Config Cheat Sheet](administration/config-cheat-sheet.md) for more information.
    23  
    24  ## Authentication
    25  
    26  Gitea supports these methods of API authentication:
    27  
    28  - HTTP basic authentication
    29  - `token=...` parameter in URL query string
    30  - `access_token=...` parameter in URL query string
    31  - `Authorization: token ...` header in HTTP headers
    32  
    33  All of these methods accept the same API key token type. You can
    34  better understand this by looking at the code -- as of this writing,
    35  Gitea parses queries and headers to find the token in
    36  [modules/auth/auth.go](https://github.com/go-gitea/gitea/blob/6efdcaed86565c91a3dc77631372a9cc45a58e89/modules/auth/auth.go#L47).
    37  
    38  ## Generating and listing API tokens
    39  
    40  A new token can be generated with a `POST` request to
    41  `/users/:name/tokens`.
    42  
    43  Note that `/users/:name/tokens` is a special endpoint and requires you
    44  to authenticate using `BasicAuth` and a password, as follows:
    45  
    46  ```sh
    47  $ curl -H "Content-Type: application/json" -d '{"name":"test"}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
    48  {"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}
    49  ```
    50  
    51  The ``sha1`` (the token) is only returned once and is not stored in
    52  plain-text.  It will not be displayed when listing tokens with a `GET`
    53  request; e.g.
    54  
    55  ```sh
    56  $ curl --url https://yourusername:password@gitea.your.host/api/v1/users/<username>/tokens
    57  [{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]
    58  ```
    59  
    60  To use the API with basic authentication with two factor authentication
    61  enabled, you'll need to send an additional header that contains the one
    62  time password (6 digitrotating token).
    63  An example of the header is `X-Gitea-OTP: 123456` where `123456`
    64  is where you'd place the code from your authenticator.
    65  Here is how the request would look like in curl:
    66  
    67  ```sh
    68  $ curl -H "X-Gitea-OTP: 123456" --url https://yourusername:yourpassword@gitea.your.host/api/v1/users/yourusername/tokens
    69  ```
    70  
    71  You can also create an API key token via your Gitea installation's web
    72  interface: `Settings | Applications | Generate New Token`.
    73  
    74  ## OAuth2 Provider
    75  
    76  Access tokens obtained from Gitea's [OAuth2 provider](development/oauth2-provider.md) are accepted by these methods:
    77  
    78  - `Authorization bearer ...` header in HTTP headers
    79  - `token=...` parameter in URL query string
    80  - `access_token=...` parameter in URL query string
    81  
    82  ### More on the `Authorization:` header
    83  
    84  For historical reasons, Gitea needs the word `token` included before
    85  the API key token in an authorization header, like this:
    86  
    87  ```sh
    88  Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675
    89  ```
    90  
    91  In a `curl` command, for instance, this would look like:
    92  
    93  ```sh
    94  curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
    95      -H "accept: application/json" \
    96      -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
    97      -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i
    98  ```
    99  
   100  As mentioned above, the token used is the same one you would use in
   101  the `token=` string in a GET request.
   102  
   103  ## Pagination
   104  
   105  The API supports pagination. The `page` and `limit` parameters are used to specify the page number and the number of items per page. As well, the `Link` header is returned with the next, previous, and last page links if there are more than one pages. The `x-total-count` is also returned to indicate the total number of items.
   106  
   107  ```sh
   108  curl -v "http://localhost/api/v1/repos/search?limit=1"
   109  ...
   110  < link: <http://localhost/api/v1/repos/search?limit=1&page=2>; rel="next",<http://localhost/api/v1/repos/search?limit=1&page=5252>; rel="last"
   111  ...
   112  < x-total-count: 5252
   113  ```
   114  
   115  ## API Guide
   116  
   117  API Reference guide is auto-generated by swagger and available on:
   118  `https://gitea.your.host/api/swagger`
   119  or on the
   120  [Gitea instance](https://gitea.com/api/swagger)
   121  
   122  The OpenAPI document is at:
   123  `https://gitea.your.host/swagger.v1.json`
   124  
   125  ## Sudo
   126  
   127  The API allows admin users to sudo API requests as another user. Simply add either a `sudo=` parameter or `Sudo:` request header with the username of the user to sudo.
   128  
   129  ## SDKs
   130  
   131  - [Official go-sdk](https://gitea.com/gitea/go-sdk)
   132  - [more](https://gitea.com/gitea/awesome-gitea#user-content-sdk)