Create or update a secret - Ara Documentation

Create or update a secret

curl --request POST \
  --url https://api.ara.so/v3/organizations/{orgId}/secrets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "NPM_TOKEN",
  "value": "npm_...",
  "note": "Used by acme/web",
  "scope": "organization"
}
'

import requests

url = "https://api.ara.so/v3/organizations/{orgId}/secrets"

payload = {
    "name": "NPM_TOKEN",
    "value": "npm_...",
    "note": "Used by acme/web",
    "scope": "organization"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'NPM_TOKEN',
    value: 'npm_...',
    note: 'Used by acme/web',
    scope: 'organization'
  })
};

fetch('https://api.ara.so/v3/organizations/{orgId}/secrets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ara.so/v3/organizations/{orgId}/secrets",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'NPM_TOKEN',
    'value' => 'npm_...',
    'note' => 'Used by acme/web',
    'scope' => 'organization'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ara.so/v3/organizations/{orgId}/secrets"

	payload := strings.NewReader("{\n  \"name\": \"NPM_TOKEN\",\n  \"value\": \"npm_...\",\n  \"note\": \"Used by acme/web\",\n  \"scope\": \"organization\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.ara.so/v3/organizations/{orgId}/secrets")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"NPM_TOKEN\",\n  \"value\": \"npm_...\",\n  \"note\": \"Used by acme/web\",\n  \"scope\": \"organization\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.ara.so/v3/organizations/{orgId}/secrets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"NPM_TOKEN\",\n  \"value\": \"npm_...\",\n  \"note\": \"Used by acme/web\",\n  \"scope\": \"organization\"\n}"

response = http.request(request)
puts response.read_body

{
  "ok": true,
  "name": "NPM_TOKEN",
  "scope": "user"
}

{
  "error": "prompt_required"
}

POST

/

v3

/

organizations

/

{orgId}

/

secrets

Create or update a secret

curl --request POST \
  --url https://api.ara.so/v3/organizations/{orgId}/secrets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "NPM_TOKEN",
  "value": "npm_...",
  "note": "Used by acme/web",
  "scope": "organization"
}
'

import requests

url = "https://api.ara.so/v3/organizations/{orgId}/secrets"

payload = {
    "name": "NPM_TOKEN",
    "value": "npm_...",
    "note": "Used by acme/web",
    "scope": "organization"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'NPM_TOKEN',
    value: 'npm_...',
    note: 'Used by acme/web',
    scope: 'organization'
  })
};

fetch('https://api.ara.so/v3/organizations/{orgId}/secrets', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.ara.so/v3/organizations/{orgId}/secrets",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'NPM_TOKEN',
    'value' => 'npm_...',
    'note' => 'Used by acme/web',
    'scope' => 'organization'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.ara.so/v3/organizations/{orgId}/secrets"

	payload := strings.NewReader("{\n  \"name\": \"NPM_TOKEN\",\n  \"value\": \"npm_...\",\n  \"note\": \"Used by acme/web\",\n  \"scope\": \"organization\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.ara.so/v3/organizations/{orgId}/secrets")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"NPM_TOKEN\",\n  \"value\": \"npm_...\",\n  \"note\": \"Used by acme/web\",\n  \"scope\": \"organization\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.ara.so/v3/organizations/{orgId}/secrets")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"NPM_TOKEN\",\n  \"value\": \"npm_...\",\n  \"note\": \"Used by acme/web\",\n  \"scope\": \"organization\"\n}"

response = http.request(request)
puts response.read_body

{
  "ok": true,
  "name": "NPM_TOKEN",
  "scope": "user"
}

{
  "error": "prompt_required"
}

Authorizations

Authorization

string

header

required

Your ara_ API key from Settings > Ara API. Keys are capability-scoped: run, plugins:read, secrets:read, secrets:write, sessions:read, knowledge:read, repos:read, repos:write, reviews:read, reviews:write, analytics:read, org:read, org:write, attachments:read, attachments:write, plugins:write, guardrails:read, guardrails:write.

Path Parameters

orgId

string

required

Organization id or slug. Resolve it with GET /v3/self.

Body

application/json

name

string

required

Uppercase identifier, e.g. NPM_TOKEN.

value

string

required

The secret value. Stored encrypted and never returned.

note

string

Optional usage guidance for agents and workspace members. Include the repository name when the secret is intended for one codebase.

Maximum string length: 2000

scope

enum<string>

default:user

Available options:

organization,

user,

repo

repo

string

Deprecated context field for the repo compatibility scope. The value is stored workspace-wide.

provider

enum<string>

Deprecated provider context for the repo compatibility scope.

Available options:

github,

gitlab

Response

Secret stored.

⌘I