Edit this page on GitHub

Home > docs > api > Secret

Secret

A secret is either a username/password or name/ssh-key pair for use in securing access to repositories and other systems. Secrets can be created and managed in the Concord Console user interface as well as the Concord REST API.

The REST API provides support for the following operations related to secrets:

Create a Secret

Creates a new secret to be stored in Concord.

  • URI /api/v1/org/${orgName}/secret
  • Method POST
  • Headers Authorization, Content-Type: multipart/form-data
  • Multipart request

    • type - mandatory, supported types:
      • key_pair - a SSH key pair, public and private key files;
      • username_password - a pair of string values;
      • data - binary or text data.
    • name - mandatory, the name of the created secret. Must be unique for the organization;
    • storePassword - optional, a password, will be used to encrypt the created secret and which can be used to retrieve it back;
    • generatePassword - optional, a boolean value. If true, the server will automatically generate and return a storePassword value;
    • visibility - optional, PUBLIC (default) or PRIVATE. See the description of public and private resources;
    • project - optional, a project name. If set, the secret can only be used in the processes of the specified project;

    The rest of the parameters depend of the type of the created secret:

    • type=key_pair:
      • public - a public key file of the key pair;
      • private - a private key file of the key pair.
    • type=username_password:
      • username - a string value;
      • password - a string value.
    • type=data:
      • data - a string or binary value.

    For type=key_pair if a public value is omitted, a new key pair will generated by the server.

  • Success response

      Content-Type: application/json
    
      {
        "id": "...",
        "result": "CREATED",
        "ok": true
      }
    

Example: Generate a new Key Pair

You can create a new key pair that is signed by the Concord server as follows:

curl -u myusername \
-F name=myKey \
-F type=key_pair \
https://concord.example.com/api/v1/org/Default/secret

After successful authentication with the provided prompted password, the server generates the new key pair and returns the public key:

{
  "id" : "e7c24546-e0e1-11e7-be9f-fa163e0708eb",
  "result" : "CREATED",
  "publicKey" : "ssh-rsa AAAAB3NzaC1...zri1 concord-server\n",
  "ok" : true
}

This key can be used a deploy key in the git repository of your project to establish the necessary trust between the Concord server and your git repository hosting system.

Example: Upload an Existing Key Pair

You can upload an existing key pair as follows:

curl -H "Authorization: auBy4eDWrKWsyhiDp3AQiw" \
-F name=myKey \
-F type=key_pair \
-F [email protected]/path/to/id_rsa.pub \
-F [email protected]/path/to/id_rsa \
https://concord.example.com/api/v1/org/Default/secret

After successful authentication with the prompted password, the server uploads and stores the files. The secret can subsequently be used within your Concord flows.

Example: Creating a Username and Password Secret

You can create a username and password secret as follows:

curl -u myusername \
-F name=myKey \
-F type=username_password \
-F username=myUser \
-F password=myPass \
https://concord.example.com/api/v1/org/Default/secret

After successful authentication with the prompted password, the server creates and stores both values with a secret. It can subsequently be used within your Concord flows.

Example: Storing a Single Value as Secret

You can store a single value as a secret on Concord as follows:

curl -u myusername \
-F name=myKey \
-F type=data \
-F data=myValue \
https://concord.example.com/api/v1/org/Default/secret

Update a Secret

Updates parameters of an existing secret.

  • URI /api/v1/org/${orgName}/secret/${secretName}
  • Method POST
  • Headers Authorization, Content-Type: application/json
  • Body
      {
        "name": "New name",
        "visibility": "PRIVATE"
      }
    

    Either name or visibility (or both) must be specified.

    Omitted parameters are not updated.

  • Success response
      Content-Type: application/json
    
      {
        "ok": true,
        "result": "UPDATED"
      }
    

<a name=”metadata>

Get Metadata of Secret

Retrieves metadata of an existing secret.

  • URI /api/v1/org/${orgName}/secret/${secretName}
  • Method GET
  • Headers Authorization
  • Body none
  • Success response
      Content-Type: application/json
    
      {
        "id": "...",
        "name": "secretName",
        "orgId": "...",
        "orgName": "...",
        "projectId": "...",
        "projectName": "...",
        "type": "...",
        "storeType": "...",
        "visibility": "..."
      }
    

Get Public SSH Key of Secret

Returns a public key from an existing key pair of a secret.

  • URI /api/v1/org/${orgName}/secret/${secretName}/public
  • Method GET
  • Headers Authorization
  • Body none
  • Success response

      Content-Type: application/json
    
      {
        "name": "secretName",
        "publicKey": "ssh-rsa AAAA... concord-server",
        "ok": true
      }
    

On a typical Concord installation you can pass your username and be quoted for the password:

curl -u username 'https://concord.example.com/api/v1/org/Default/secret/myKey/public'

The server provides a JSON-formatted response similar to:

{
  "name" : "myKey",
  "publicKey" : "ssh-rsa ABCXYZ... concord-server",
  "ok" : true
}

The value of the publicKey attribute represents the public key of the newly generated key.

The value of the name attribute e.g. myKey identifies the key for usage in Concord.

Delete a Secret

Deletes a secret and associated keys.

  • URI /api/v1/org/${orgName}/secret/${secretName}
  • Method DELETE
  • Headers Authorization
  • Body none
  • Success response

      Content-Type: application/json
    
      {
        "ok": true
      }
    

List Secrets

List all existing secrets in a specific organization.

  • Permissions
  • URI /api/v1/org/${orgName}/secret
  • Method GET
  • Body none
  • Success response

      Content-Type: application/json
    
      [
        { "name": "...", "type": "..." },
        { "name": "...", "type": "..." }
      ]