Skip to content

Authentication and connection

There is exactly one connection pattern in this collection, used identically by every module and every example in these docs: an API key, preferably supplied through the environment. Learn it once, reuse it everywhere.

The pattern

export NETORCA_API_URL=https://api.example.netorca.io
export NETORCA_API_KEY=xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export NETORCA_CONTEXT=serviceowner       # optional; this is the default

# tasks then carry no connection boilerplate at all
- name: My in-service items
  netautomate.netorca.netorca_service_item_info:
    runtime_state: [IN_SERVICE]
Environment variable Module parameter Default
NETORCA_API_URL api_url - (required)
NETORCA_API_KEY api_key - (required)
NETORCA_CONTEXT context serviceowner
NETORCA_VALIDATE_CERTS validate_certs true

Module parameters win over environment variables when both are set. The URL is normalised to end in a single /v1, so both https://api.example.netorca.io and https://api.example.netorca.io/v1 work.

Getting an API key

API keys belong to a team and carry that team's permissions. Generate one in the NetOrca GUI under your team's settings (see the platform documentation for the walkthrough). The NetOrca API is API-key only - there is no username/password mode (v1's username/password parameters are gone; the migration guide covers it).

A note on two often-confused service flags: allow_manual_approval / allow_manual_completion govern only whether humans may approve/complete from the GUI. API transitions - what these modules perform - are always available to the service-owning team's key. A 403 on approve or complete therefore means the key's team does not own the service or the context is wrong, never a missing flag.

Context: which side of the service are you on?

Every request runs as either serviceowner (the services your team offers: the requests made against them, their items, their deployed records - the side that approves and fulfils) or consumer (what your team consumes: your declared items, your own requests). Same modules, same filters - different scope:

- name: Requests made against my services (I am the provider)
  netautomate.netorca.netorca_change_instance_info:
    state: [PENDING]

- name: Requests my own team made (I am the customer)
  netautomate.netorca.netorca_change_instance_info:
    context: consumer
    state: [PENDING]

Set NETORCA_CONTEXT=consumer to flip a whole pipeline, or the context parameter per task.

Where the key lives, per environment

A git-ignored .env in your project (this repo's integration runner sources it automatically):

# .env - in .gitignore, never committed
NETORCA_API_URL=https://api.sandbox.netorca.io
NETORCA_API_KEY=...

Settings → CI/CD → Variables: add NETORCA_API_URL and NETORCA_API_KEY as Masked (and Protected if only protected branches deploy). Jobs then just run ansible-playbook - the modules pick the variables up from the environment.

Create a custom credential type so the key is stored encrypted and injected as environment variables:

# inputs
fields:
  - id: netorca_api_url
    type: string
    label: NetOrca API URL
  - id: netorca_api_key
    type: string
    label: NetOrca API key
    secret: true
required: [netorca_api_url, netorca_api_key]

# injectors
env:
  NETORCA_API_URL: "{{ netorca_api_url }}"
  NETORCA_API_KEY: "{{ netorca_api_key }}"

Attach a credential of this type to the job templates that run your NetOrca playbooks.

If you must keep the key in the repository, encrypt it and pass it as a parameter:

- name: Query with a vaulted key
  netautomate.netorca.netorca_service_item_info:
    api_url: "https://api.example.netorca.io"
    api_key: "{{ vaulted_netorca_api_key }}"

Secrecy properties

  • api_key is declared no_log - it never appears in task output, diffs or callbacks.
  • Never write a key literal into a playbook or commit one to Git (the v1-era demo playbooks did; the scenario page shows the structural fix).
  • Rotate by generating a new team key, updating the variable in one place (CI variable / AWX credential / .env), and revoking the old one.

TLS

validate_certs defaults to true. Disable it only for lab instances with self-signed certificates - never in production:

    - name: Lab instance with a self-signed cert
      netautomate.netorca.netorca_service_item_info:
        validate_certs: false