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.
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
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
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>' https://api.codeship.com/v2/auth # 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" https://api.codeship.com/v2/organizations/<your-org-uuid-from-auth-response>/projects -v