Global Parameters

Endpoints for managing global parameters.

Global parameters allow you to define reusable, configurable values that can be referenced across your entire Opsera organization. Unlike pipeline parameters which are scoped to a specific pipeline, global parameters are available organization-wide.

---

Key Features

• Organization-Wide Access: Define parameters once, use across all pipelines and tasks

• Role-Based Access Control: Parameters respect RBAC permissions

• Vault Integration: Sensitive parameter values can be stored securely in vault

• Flexible Scoping: Support for different scope levels within your organization

• Lookup Lists: Parameters can reference lookup lists for dynamic values

---

Common Use Cases

• Environment Variables: Store environment-specific configurations (dev, staging, prod)

• Secrets Management: Secure storage of API keys, credentials, tokens with vault integration

• Organization Standards: Define standard values like naming conventions, URLs, endpoints

• Shared Configuration: Configuration values used across multiple pipelines and tasks

• Dynamic Values: Use lookup lists for values that change based on context

---

Parameter Structure

Each global parameter includes:

• _id: Unique identifier (MongoDB ObjectId)

• name: Human-readable parameter name

• value: The parameter value

• scope: Optional scope for parameter visibility

• parentId: Optional parent ID for hierarchical organization

• active: Whether the parameter is active

• vaultEnabled: Whether the value is stored in vault

• vaultKey: Key used for vault storage (if vaultEnabled)

• selectField: Whether this is a select field type

• lookupListId: Reference to a lookup list for dynamic values

• roles: Array of role assignments for access control

• tags: Array of tags for categorization

• createdAt: Timestamp of creation

• updatedAt: Timestamp of last update

Get All Global Parameters

get

Retrieves all global parameters that the user has access to.

This endpoint returns an array of all global parameters defined in the organization, along with a count of total parameters. Parameters are filtered based on the user's role-based access permissions.

Query Filters

• search: Filter by keyword in parameter name

• encrypted: Filter to show only encrypted (vault-enabled) parameters

• unencrypted: Filter to show only unencrypted parameters

• scope: Filter by parameter scope

• parentId: Filter by parent ID for hierarchical parameters

Access Control

• User must have read access to global parameters

• Returns only parameters the user is authorized to view based on RBAC

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Query parameters

searchstringOptional

Keyword to filter parameters by name

Example: api-key

encryptedbooleanOptional

Filter to show only vault-enabled parameters

Example: true

unencryptedbooleanOptional

Filter to show only non-vault parameters

Example: false

scopestringOptional

Filter by parameter scope

Example: production

parentIdstringOptional

Filter by parent ID (MongoDB ObjectId)

Example: 507f1f77bcf86cd799439011Pattern: ^[a-zA-Z0-9]{24}$

Responses

200

Successfully retrieved global parameters

application/json

countintegerOptional

Total number of parameters returned

Example: 3

401

Authentication failed

403

Access denied - User lacks permission to view global parameters

500

Internal server error

get

/api/v2/global-parameters/

HTTPcURLJavaScriptPython

GET /api/v2/global-parameters/ HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "count": 2,
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "opsera-global-api-key",
      "value": "sk-1234567890abcdef",
      "scope": "",
      "parentId": "",
      "active": true,
      "vaultEnabled": true,
      "vaultKey": "global-api-key-vault",
      "selectField": false,
      "lookupListId": "",
      "roles": [
        {
          "role": "administrator",
          "user": "[email protected]",
          "group": null
        }
      ],
      "tags": []
    },
    {
      "_id": "507f1f77bcf86cd799439012",
      "name": "opsera-deploy-environment",
      "value": "production",
      "scope": "",
      "parentId": "",
      "active": true,
      "vaultEnabled": false,
      "vaultKey": "",
      "selectField": false,
      "lookupListId": "",
      "roles": [
        {
          "role": "administrator",
          "user": "[email protected]",
          "group": null
        }
      ],
      "tags": [
        "environment"
      ]
    }
  ]
}

Create a Global Parameter

post

Creates a new global parameter that can be used across the organization.

Global parameters provide a way to store and manage configuration values that can be referenced by pipelines and tasks throughout your organization.

Vault Integration

• Set vaultEnabled: true to store the value securely in vault

• Vault-enabled parameters have their values encrypted at rest

• Use vault for sensitive data like API keys, credentials, tokens

Role-Based Access Control

• Specify roles array to control who can access this parameter

• Role types include: administrator, power_user, user

• Roles can be assigned to users or groups

Naming Conventions

• Use descriptive names that indicate the parameter's purpose

• Names must be unique within the organization

• Consider using prefixes for categorization (e.g., prod-, dev-)

Access Control

• User must have permission to create global parameters

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Body

application/json

namestringRequired

Parameter name (must be unique within the organization)

Example: opsera-global-parameter-example

valuestringRequired

Parameter value

Example: my-parameter-value

scopestringOptional

Optional scope for parameter visibility

parentIdstringOptional

Optional parent ID for hierarchical organization

activebooleanOptional

Whether the parameter is active (defaults to true)

Example: true

vaultEnabledbooleanOptional

Whether the value should be stored securely in vault

Example: true

vaultKeystringOptional

Key to use for vault storage

selectFieldbooleanOptional

Whether this is a select field type

Example: false

lookupListIdstringOptional

Reference to a lookup list for dynamic values

tagsstring[]Optional

Array of tags for categorization

Responses

200

Parameter created successfully

application/json

400

Bad Request - Invalid input or duplicate parameter name

401

Authentication failed

403

Access denied - User lacks permission to create global parameters

500

Internal server error

post

/api/v2/global-parameters/create

HTTPcURLJavaScriptPython

POST /api/v2/global-parameters/create HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 197

{
  "name": "opsera-deploy-environment",
  "value": "production",
  "active": true,
  "vaultEnabled": false,
  "selectField": false,
  "roles": [
    {
      "role": "administrator",
      "user": "[email protected]",
      "group": null
    }
  ],
  "tags": []
}

Basic parameter without vaultVault-enabled secure parameter

{
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "opsera-global-parameter-example",
    "value": "my-parameter-value",
    "scope": "",
    "parentId": "",
    "active": true,
    "vaultEnabled": true,
    "vaultKey": "",
    "selectField": false,
    "lookupListId": "",
    "roles": [
      {
        "role": "administrator",
        "user": "[email protected]",
        "group": null
      }
    ],
    "tags": [],
    "createdAt": "2026-03-26T14:12:09.468Z",
    "updatedAt": "2026-03-26T14:12:09.468Z"
  }
}

Get a Global Parameter by ID

get

Retrieves a single global parameter by its unique identifier.

This endpoint returns the complete parameter object including all metadata. For retrieving only the parameter value, use the /api/v2/global-parameters/{customParameterId}/value endpoint.

Access Control

• User must have read access to this specific global parameter based on RBAC

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

customParameterIdstringRequired

The MongoDB ObjectId of the global parameter

Example: 507f1f77bcf86cd799439011Pattern: ^[a-zA-Z0-9]{24}$

Responses

200

Successfully retrieved global parameter

application/json

400

Bad Request - Invalid parameter ID format

401

Authentication failed

403

Access denied - User lacks permission to view this parameter

404

Parameter not found

500

Internal server error

get

/api/v2/global-parameters/{customParameterId}

HTTPcURLJavaScriptPython

GET /api/v2/global-parameters/{customParameterId} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "opsera-global-parameter-example",
    "value": "my-parameter-value",
    "scope": "",
    "parentId": "",
    "active": true,
    "vaultEnabled": true,
    "vaultKey": "",
    "selectField": false,
    "lookupListId": "",
    "roles": [
      {
        "role": "administrator",
        "user": "[email protected]",
        "group": null
      }
    ],
    "tags": [],
    "createdAt": "2026-03-26T14:12:09.468Z",
    "updatedAt": "2026-03-26T14:12:09.468Z"
  }
}

Delete a Global Parameter

delete

Deletes a global parameter by its unique identifier.

This operation is permanent and cannot be undone. Any pipelines or tasks that reference this parameter will need to be updated to remove the reference or the execution may fail.

Important Considerations

• Irreversible: Deletion is permanent

• Impact Assessment: Ensure no active pipelines or tasks reference this parameter

• Audit Trail: Deletion is logged for audit purposes

• Vault Cleanup: If vault-enabled, the vault entry will also be removed

Access Control

• User must have write access to this specific global parameter based on RBAC

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

customParameterIdstringRequired

The MongoDB ObjectId of the global parameter to delete

Example: 507f1f77bcf86cd799439011Pattern: ^[a-zA-Z0-9]{24}$

Responses

200

Parameter deleted successfully

application/json

messagestringOptionalExample: Delete Successful

400

Bad Request - Invalid parameter ID format

401

Authentication failed

403

Access denied - User lacks permission to delete this parameter

404

Parameter not found

500

Internal server error

delete

/api/v2/global-parameters/{customParameterId}

HTTPcURLJavaScriptPython

DELETE /api/v2/global-parameters/{customParameterId} HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "message": "Delete Successful"
}

Update a Global Parameter

post

Updates an existing global parameter by its unique identifier.

Partial Updates

This endpoint supports partial updates. Only include the fields you want to change in the request body. Required fields are automatically populated from the existing parameter.

Updateable Fields

Only the following fields can be updated after creation:

Field	Type	Description
value	string	The parameter value
roles	array	Access control role assignments

All other fields (name, scope, parentId, active, vaultEnabled, tags, etc.) are immutable after creation. Attempting to modify immutable fields will result in an error.

Access Control

• User must have write access to this specific global parameter based on RBAC

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

customParameterIdstringRequired

The MongoDB ObjectId of the global parameter

Example: 507f1f77bcf86cd799439011Pattern: ^[a-zA-Z0-9]{24}$

Body

application/json

valuestringOptional

The new parameter value

Example: new-updated-value

Responses

200

Parameter updated successfully

application/json

400

Bad Request - Invalid input, parameter ID format, or attempted to update immutable field

401

Authentication failed

403

Access denied - User lacks permission to update this parameter

404

Parameter not found

500

Internal server error

post

/api/v2/global-parameters/{customParameterId}/update

HTTPcURLJavaScriptPython

POST /api/v2/global-parameters/{customParameterId}/update HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "value": "new-updated-value"
}

Update value onlyUpdate roles onlyUpdate value and roles

{
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "opsera-global-parameter-example",
    "value": "my-parameter-value",
    "scope": "",
    "parentId": "",
    "active": true,
    "vaultEnabled": true,
    "vaultKey": "",
    "selectField": false,
    "lookupListId": "",
    "roles": [
      {
        "role": "administrator",
        "user": "[email protected]",
        "group": null
      }
    ],
    "tags": [],
    "createdAt": "2026-03-26T14:12:09.468Z",
    "updatedAt": "2026-03-26T14:12:09.468Z"
  }
}

Get Global Parameter Value Only

get

Retrieves only the value of a global parameter by its unique identifier.

This endpoint returns just the parameter value without the full parameter metadata. Use this for lightweight value retrieval during pipeline execution or when only the value is needed.

Use Cases

• Pipeline Execution: Quick value lookup during step execution

• Script Integration: Retrieve values for external scripts or tools

• Validation: Verify parameter values before pipeline runs

• API Integration: Get values for use in external API calls

Comparison with Full Parameter Endpoint

• GET /api/v2/global-parameters/{customParameterId} - Returns complete parameter object

• GET /api/v2/global-parameters/{customParameterId}/value - Returns only the value (this endpoint)

Access Control

• User must have read access to this specific global parameter based on RBAC

Authorizations

bearerAuth

AuthorizationstringRequired

API authentication using Bearer tokens. Include your API token in the Authorization header: Authorization: Bearer <your-api-token>

Tokens can be obtained from the Opsera platform's API token management interface.

Path parameters

customParameterIdstringRequired

The MongoDB ObjectId of the global parameter

Example: 507f1f77bcf86cd799439011Pattern: ^[a-zA-Z0-9]{24}$

Responses

200

Successfully retrieved parameter value

application/json

dataone ofOptional

The parameter value

stringOptional

or

numberOptional

or

booleanOptional

or

objectOptional

400

Bad Request - Invalid parameter ID format

401

Authentication failed

403

Access denied - User lacks permission to view this parameter

404

Parameter not found

500

Internal server error

get

/api/v2/global-parameters/{customParameterId}/value

HTTPcURLJavaScriptPython

GET /api/v2/global-parameters/{customParameterId}/value HTTP/1.1
Host: api.[organization].opsera.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": "sk-1234567890abcdef"
}