2 minute read

Access and permissions

Access to the API generally relies on the teams and users setup as part of your project or organization setup. If a user is able to see a project in the web console, the same user will be able to access the same project via the API.

Setting up access

The user you expect to access the API will need to have access to the project(s) you want to manipulate via the API.

We recommend you create users specifically for accessing the API, primarily so that you can better control what is accessed via the API. Users that want to access the API also need to have a password account on CodeShip, so regular GitHub/GitLab/Bitbucket accounts will not work. Accounts with two factor authentication will also not work.

To create a new user, simply invite them using an appropriate email address. You can invite users and generally manage your teams and users via the Teams link in the top navigation bar of the web console.


Generally there are three levels of permisions:

  • Manager - can do everything

  • Project Manager - can do everything except user/team management and billing

  • Contributor - can only view

When an account is initially created, a team called Owners is created with Manager permissions. Users in this group will have access to all projects in the organization. If you want to either restrict which projects a user will have access to, or limit the level of access, you’ll need to set up a new team first. See the managing teams documentation for more details.

Authentication endpoint

The authentication endpoint uses Basic Auth to authenticate the user and return an auth token.

Once you have the token, you’ll need to make sure to include it in every subsequent request to the API. How to supply the header depends on the language and framework you use, but generally you’ll need to add a header called Authorization with the word Bearer in front of your token.

If you’re trying out the API using curl, this could look like:

-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMzI2MDMsInNjb3BlcyI6eyIzMzU3YjFkMC1iOTlkLTAxMzQtMzA2NC00MmUzYzNjMjRkN2QiOlsicHJvamVjdC5yZWFktiwicHJvamVjdC53cml0ZSIsImJ1aWxkLnJlYWQiLCJidWlsZC53cml0ZSJdLCI2NzZkNGY1MC1lOTNkLTAxMzMtYjUzZS03NmJlZjhkN2IxNGYiOlsicHJvamVj3C5yZWFkIiwicHJvamVjdC53cml0ZSIsImJ1aWxkLnJlYWQiLCJidWlsZC53cml0ZSJdLCI3MjFjZWExMC1iNjk1LTAxMzQtNWI5NC01MjQwYzQ4MWM1NjIiOlsifHJvamVjdC5yZWFkIiwicHJvamVjdC53cml0ZSIsImJ1aWxkLnJlYWQiLCJidWlsZC53cml0ZSJdfSwiZXhwIjoxNTEyNjg3NzM0LCJhZG1pbiI6ZmFsc2UsImlzcyI6Imh0dHBzOi8vYXBpLmNvZGVzaGlwLmNvbS92Mi8iLCJhdWQiOiJjbGllbnQiLCJpYXQiOjE1MTI2ODQxMzQsImp0aSI6ImM2MWI3NjU3NTVlM2ZhZTI1MDEzMDhmZTMxYmNmODc1In0.jwBhLKGZmK24HwrcqoG-vZWfsB5uQYgbhh5qd2XrMEQ"
The token expires after an hour, so you will need to plan to reauthenticate if you get a 401 error from one of the endpoints.


Below is a short example to try out authenticating with your own credentials and make sure things work as expected. The example assumes that you have curl installed, which is usually included with most macOS and Linux versions.

# First authenticate # The response will contain your token and details on the organizations you have access to curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" --user '<your email>:<your password>' # Setting the token as an environment variable saves from copy/pasting it each time export TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxMzI2MDMsInNjb3BlcyI6eyIzMzU3YjFkMC1iOTlkLTAxMzQtMzA2NC00MmUzYzNjMjRkN2QiOlsicHJvamVjdC5yZWFktiwicHJvamVjdC53cml0ZSIsImJ1aWxkLnJlYWQiLCJidWlsZC53cml0ZSJdLCI2NzZkNGY1MC1lOTNkLTAxMzMtYjUzZS03NmJlZjhkN2IxNGYiOlsicHJvamVj3C5yZWFkIiwicHJvamVjdC53cml0ZSIsImJ1aWxkLnJlYWQiLCJidWlsZC53cml0ZSJdLCI3MjFjZWExMC1iNjk1LTAxMzQtNWI5NC01MjQwYzQ4MWM1NjIiOlsifHJvamVjdC5yZWFkIiwicHJvamVjdC53cml0ZSIsImJ1aWxkLnJlYWQiLCJidWlsZC53cml0ZSJdfSwiZXhwIjoxNTEyNjg3NzM0LCJhZG1pbiI6ZmFsc2UsImlzcyI6Imh0dHBzOi8vYXBpLmNvZGVzaGlwLmNvbS92Mi8iLCJhdWQiOiJjbGllbnQiLCJpYXQiOjE1MTI2ODQxMzQsImp0aSI6ImM2MWI3NjU3NTVlM2ZhZTI1MDEzMDhmZTMxYmNmODc1In0.jwBhLKGZmK24HwrcqoG-vZWfsB5uQYgbhh5qd2XrMEQ # Now get a list of projects from one of your organizations curl -XGET -H "Content-Type: application/json" -H "Accept: application/json" -H "Authorization: Bearer $TOKEN"<your-org-uuid-from-auth-response>/projects -v