Getting started
IntroductionInstalled packagesEnvironment variablesDebugging buildsCachingParallel testingDeployment pipelinesRunning commands as rootIgnoring commandsRun a command in case of an errorSetting timezoneAccess to other repositoriesUsing scriptsGit LFSUbuntu 20.04 Focal
IntroductionFTP/SSH/SFTP/RSYNCCustom scriptHerokuHeroku MigrationAWS Elastic BeanstalkAWS CodeDeployAWS LambdaAWS S3Google App EngineAWS CLIgcloud CLIAzure CLIDigital OceanEngine YardCapistranoGit PushCloudFoundryCloud66anynines
IntroductionBrowser testingBackground commandsGit submodulesCustom DNSArtifacts
IntroductionCassandraCouchDBDynamoDBMongoDBMySQLPostgreSQLSQLite
IntroductionDartElixirGoJava and JVMMeteorNode.jsPHPPythonRubyRust
IntroductionBeanstalkdRabbitMQRedis
IntroductionElasticsearchMemcachedSphinx
IntroductionCloudBees CodeShip Pro introduction guideCloudBees CodeShip Pro introduction guide 2CloudBees CodeShip Pro introduction guide 3CloudBees CodeShip Pro introduction guide 4CloudBees CodeShip Pro introduction guide 5
Migrating to CloudBees CodeShip Pro
Docker for CI/CD
Getting started with CloudBees CodeShip Pro overview and resources
IntroductionServices configSteps configEnvironment variablesImage registriesImage cachingBuild argumentsVolumesHandling secretsMultiple reposServices and databasesSetting an SSH private keyPreinstalled images
IntroductionInstallationUsing the Jet CLIjet cleanupjet decryptjet encryptjet generatejet loadjet runjet stepsjet updatejet validatejet version
IntroductionAWSAWS S3AWS EBAWS ECSAWS EKSAWS CodeDeployAzure Container ServiceHerokuGoogle CloudGoogle App EngineGoogle Cloud FunctionsGoogle Container EngineGoogle Compute EngineKubernetesTerraformDeploy Via SSHDocker SwarmIBM Cloud FoundryIBM Cloud Container Service
IntroductionBrowser testingParallel testing
IntroductionElixirGoJava and JVMNode.jsPHPPythonRuby
IntroductionCaching multi-stage DockerfileContainer is slow to exitDiffering results with Jet CLIDocker Hub rate limitingManaging multiple environments for a serviceReducing log output from dependent containersStep log not appearingUsing env vars in command steps

Authentication

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.

Permissions

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.

Example

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>' 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
▼
POST authenticate