API Usage

Authentication

DevOps Control supports these methods of API authentication:

  • HTTP basic authentication
  • token=... parameter in URL query string
  • access_token=... parameter in URL query string
  • Authorization: token ... header in HTTP headers

All of these methods accept the same API key token type.

Generating and listing API tokens

A new token can be generated with a POST request to /users/:name/tokens.

Note that /users/:name/tokens is a special endpoint and requires you to authenticate using BasicAuth and a password, as follows:

$ curl -H "Content-Type: application/json" -d '{"name":"test"}' -u username:password https://gitea.your.host/api/v1/users/<username>/tokens
{"id":1,"name":"test","sha1":"9fcb1158165773dd010fca5f0cf7174316c3e37d","token_last_eight":"16c3e37d"}

The sha1 (the token) is only returned once and is not stored in plain-text. It will not be displayed when listing tokens with a GET request; e.g.

$ curl --url https://yourusername:password@gitea.your.host/api/v1/users/<username>/tokens
[{"name":"test","sha1":"","token_last_eight:"........":},{"name":"dev","sha1":"","token_last_eight":"........"}]

You can also create an API key token via your DevOps Control installation's web interface: Settings | Applications | Generate New Token.

More on the Authorization: header

For historical reasons, DevOps Control needs the word token included before the API key token in an authorization header, like this:

Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675

In a curl command, for instance, this would look like:

curl "http://localhost:4000/api/v1/repos/test1/test1/issues" \
    -H "accept: application/json" \
    -H "Authorization: token 65eaa9c8ef52460d22a93307fe0aee76289dc675" \
    -H "Content-Type: application/json" -d "{ \"body\": \"testing\", \"title\": \"test 20\"}" -i

As mentioned above, the token used is the same one you would use in the token= string in a GET request.

Pagination

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.

curl -v "http://localhost/api/v1/repos/search?limit=1"
...
< 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"
...
< x-total-count: 5252

API Guide

The API Guide is available in the DevOps Control UI. Most pages have an API link located at the bottom right corner.

Sudo

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.