Opsera allows users to generate personal access tokens which can be used with the Opsera API via standard RESTful APIs. Below is the documentation around creating and managing tokens and calling the supported Opsera APIs.
Personal Access Tokens
Users can generate and manage multiple personal access tokens. These tokens have a limited expiration date, targeted scope and can be expired early via the Opsera Portal if need be.
Generating a Token:
Log into the Opsera portal and click on your user name in the top right corner of the header and choose Profile:
Then select Access Tokens from the menu tab:
From this page users can create new tokens giving them unique names and setting their expiration windows and they can view the list current tokens and when they will expire. If a token is lost or no longer needed, users can expire that token in the table view below.
Token Lifecycle:
Tokens are never saved within the Opsera platform. It is the user’s responsibility to save it securely when generated, otherwise the token is lost.
When a token is created, Opsera will save only meta data about that token in the system. This is what is shown in the list of tokens at the bottom of the Personal Access Tokens page (see image above).
Tokens are generated with predefined scope. This means that a token with a pipeline scope can ONLY be used to perform pipeline actions. It could not be used for any other part of Opsera Platform’s APIs.
Tokens only work for explicitly defined Opsera API’s. A token will not work against any other API in the system.
When a new token is generated and the user saves it locally, they can then use it in tools like Postman or directly in their own scripts when calling the Opsera APIs treating it as a standard JWT based bearer token.
Token Access Rules:
A token follows the same access roles as the Portal UI. So if a user is a site Administrator OR site Power User, then they will have access to run the API’s against any supported objects (pipelines) in their organization.
If the user is the owner of the object (pipeline owner) then they will be allowed full access to perform actions on that item (same as in the UI).
Otherwise the system will evaluate the Role Access configuration for the object (as defined in the UI). So the user must be granted either the administrator, manager or user role at the object level in order to use the API.
In short the token acts just like a end user in the Portal. They must have proper access in order to perform the action. And if they do not, then the API simply returns “forbidden” to the end user.
Authentication Log:
Every time a token is used, the activity is logged in your Authentication Log. This log can be used to troubleshoot calls to the API and also ensure you are the only one using a token. You can view this for an individual token or for all of your tokens as shown below OR via the Opsera Audit Logging Token API (which itself would require a valid token).
Customer Platform APIs
The following API’s are available for integration with customer scripts or automation tools. The above token rules apply for all. Please note, get requests for tools or pipelines are limited to max of 1000 records. There is almost NO data validation on the create/update behavior, so if bad data (or malicious data) is posted to this API, there is no stopping it from breaking things.
API Servers:
Testing: https://api.opsera-test.opsera.io
Production: https://app.opsera.io
URL | METHOD | DESCRIPTION | DATA | RESPONSE |
|---|---|---|---|---|
| POST | Used for testing as a pipeline scope. It requires valid data for a given pipeline/owner but doesn’t actually trigger anything in the pipeline. It’s used to mirror the concept of the run pipeline below for testing and development. | {
"pipelineId":"5fd56d90979ee048ee660624"
}
| {
"status": "success",
"message": "it seems to be working",
"reqBody": {
"pipelineId": "5fd56d90979ee048ee660624",
"customerId": "5e46fb7ec3fa752bd2f3b990"
},
"reqToken": {
"owner": "opsera",
"userName": "OpsERA",
"email": "support@opsera.io",
"userId": "5e1cbf251c26d68f7ce6361e",
"scope": "pipeline",
"tokenId": "6025748a0809e88dd5337722",
"iat": 1613067402,
"exp": 1615659402
}
}
|
| POST | Triggers a run operation on the pipeline which returns the status, a message and the run count for the new run. | {
"pipelineId":"5fd56d90979ee048ee660624"
}
| {
"status": "executed",
"message": "Run pipeline request submitted successfully for (5fd56d90979ee048ee660624)",
"runCount": 2
}
OR {
"status": "failed",
"message": "Pipeline 5fd56d90979ee048ee660624 is currently in a paused state. Will not start another job until this pending status is resolved."
}
|
| POST | Gets the status of a pipeline based on the run count. So this can work against the current run or prior runs from a historical perspective. | {
"pipelineId":"5fd56d90979ee048ee660624",
"runCount": 3
}
| {
"status": "success",
"message": "Pipeline: Blank Template's Run 3 was successful."
}
|
| POST | Resets the pipeline to the beginning, clearing out any current run data. | {
"pipelineId":"5fd56d90979ee048ee660624"
}
| "status": "success",
"message": "The pipeline run status has been reset."
}
|
| POST | Stops a running pipeline. This action will post a stop operation to kafka for supported tools, but the pipeline job will finish it’s current operaiton and then shut down. This is not a hard stop operation. | {
"pipelineId":"5fd56d90979ee048ee660624"
}
| {
"status": "success",
"message": "The pipeline has been stopped."
}
|
| POST | Gets the pipeline data by ID | {
"pipelineId":"5fd56d90979ee048ee660624"
}
| Returns full JSON data object of pipeline. |
| POST | Gets pipeline activity logs. Optional runCount can be passed as integer. Data is limited to a max of 1000 records and is always sorted by most recent activity first. The “type” property of the POST body is optional. If that exact string “console output” is passed, it will restrict the logs being returned to the console log activity for that given run. | {
"pipelineId":"5fd56d90979ee048ee660624",
"runCount": 2,
"type":"console output" //optional value
}
| Array of pipeline activity logs. |
| POST | Passes a pipeline ID and then the data object properties of pipeline you wish to update. This can be as much or as little of the root pipeline object as long as the data structure is preserved. It’s advised not to send the “_id” but it isn’t going to break things. Same with the createdAt or updatedAt. This allows for strategic updates of just the root properties of the pipeline data object or the whole thing. | {
"pipelineId":"5fd56d90979ee048ee660624",
"pipeline": {
"name":"Updated Pipeline Via CLI",
"description": "Updating the description here through customer API. Fingers crossed"
}
}
| Returns the updated pipeline data object in its entirety. |
| POST | This will accept a full pipeline JSON data object and create it. This requires a name, account, organizationName but if other data points are excluded, it could break the UI or have other unforeseen consequences, so be VERY CAREFUL to ensure the data is right. | {
"workflow": {
"source": {
"default_tools_configurations": [],
"name": "",
"service": "",
"repository": "",
"branch": "",
"key": "",
"trigger_active": false
},
"schedule": {
"start_date": null,
"end_date": null,
"frequency": ""
},
"last_step": {},
"last_run": {},
"plan": [],
"run_count": 0
},
"tags": [
{
"type": "pipeline",
"value": "python"
}
],
"type": [],
"roles": [],
"owner": "5e46fb7ec3fa752bd2f3b990",
"organizationName": "opsera",
"account": "org-opsera-dnd-acc0",
"name": "Updated Pipeline Via CLI",
"template": "5efc6fabaf75e201aa8c4a7e",
"description": "Updating the description here through customer API. Fingers crossed",
"active": true,
}
| Returns the new pipeline object in JSON format |
| GET | Gets the list of all tools (with all JSON data) that they have access to. | n/a | Returns an array of tool objects in JSON format |
| POST | Gets a tool registry JSON object with ALL data about that tool by ID. | {
"toolId":"5fc7a12ebed9dd3a622f5d22"
}
| Returns the full tool object in JSON format. |
| POST | Passes a tool registry ID and then the data object properties of that tool in JSON that you wish to update. This can be as much or as little of the root JSON object as long as the data structure is preserved. It’s advised not to send the “_id” but it isn’t going to break things. Same with the createdAt or updatedAt. This allows for strategic updates of just the root properties of the pipeline data object or the whole thing. | {
"toolId":"5fd56d90979ee048ee660624",
"tool": {
"name":"Updated Tool Name Via CLI",
"description": "Updating the description here through customer API. Fingers crossed"
}
}
| Returns the updated tool object in JSON format |
| GET | Gets the list of all pipelines (with all JSON data) the user token has access to | n/a | Returns an array of pipeline objects in JSON format |
| POST | This will accept a full tool registry JSON data object and create it. This requires a name, account, Also, this does NOT trigger any saving to vault activity or job creation. All this does is save the summary tool registry record in the database. | {
"projects": [],
"tags": [],
"accounts": [],
"tool_tagging": [],
"name": "Bit Bucket Server Raj",
"description": "",
"tool_identifier": "bitbucket",
"costCenter": "",
"compliance": [],
"licensing": [],
"location": [],
"classification": "",
"contacts": [],
"applications": [],
"organization": [],
"external_reference": [],
"active": true,
"roles": [],
"status": "",
"tool_type_identifier": "source",
"owner": "5e1cbf251c26d68f7ce6361e",
"account": "org-opsera-dnd-acc0",
"jobs": [],
"actions": [],
"configuration": {}
}
| |
| GET | Gets the User Activity Logs for the system. This is a route limited to Site Admins and Power users and requires a token of either API scope or Security Logs scope. If no date parameter is passed, the last 7 days of logs will be returned (up to a max of 1000 records) | Optional Query Parameters:
| {
"count": 6,
"data": [
{
"_id": "61042540e1d666c9ded178c4",
"user_id": "5e1cbf251c26d68f7ce6361e",
"user_email": "support@opsera.io",
"type": "pipeline",
"action": "update",
"target_id": "5fbe589a0fae8b021e137534",
"account": "org-opsera-dnd-acc0",
"createdAt": "2021-07-30T16:13:52.109Z",
"updatedAt": "2021-07-30T16:13:52.109Z",
"__v": 0
},
]
}
|
| GET | Gets the Personal Access Tokens' Activity Logs. This is a route limited to Site Admins and Power users and requires a token of either API scope or Security Logs scope. If no date parameter is passed, the last 7 days will be returned.(up to a max of 1000 records) | Optional Query Parameters:
| {
"count": 6,
"data": [
{
"_id": "61057f3a1429a35336563240",
"token_id": "61043b2bbcb6d95b55adc5fd",
"scope": "api",
"target": "/v1/logs/user/tokens",
"user_id": "5e1cbf251c26d68f7ce6361e",
"account": "org-opsera-dnd-acc0",
"createdAt": "2021-07-31T16:50:02.242Z",
"updatedAt": "2021-07-31T16:50:02.242Z",
"__v": 0
},
]
}
|