Skip to main content

Client credential grants configuration

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to the Device Configuration APIs section in the VAPIX Library.

warning

This API is in BETA stage and provided for testing purposes. It is subject to backward-incompatible changes, including modifications to its functionality, behavior and availability. The API should not be used in production environments.

The VAPIX® Client Credentials Grant API enables secure machine-to-machine communication by providing a mechanism that can be used to exchange authorization credentials with the help of JWKS (JSON Web Key Set).

Use cases​

Set all settings​

All Client Credentials Grant settings can be set at the same time with the auth config entity.

Specify the JWKS verification URI for access token verification​

Enter the claim that is required by a token that allows the correct access level to initiate the request. The claim is required for all API requests and one of admin/operator/viewer should be used to assign the proper access level.

PATCH /config/rest/oauth-ccgrant/v1beta/AuthEntity HTTP/1.1
HOST: my-device
Content-Type: application/json

{
    "data": {
        "CCG_AuthzAdminClaim": "example-claim-admin",
        "CCG_AuthzOperatorClaim": "example-claim-operator",
        "CCG_AuthzViewerClaim": "example-claim-viewer",
        "CCG_OAuth2TokenVerify": "https://example.jwksverify.uri",
        "CCG_RequireClaim": "example-claim"
    }
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Get all settings​

Read out the current Client Credentials Grant settings from the auth entity.

The JWKS verification URI used for access token verification​

Enter the claim that is required by a token that allows the correct access level to initiate the request. The claim is required for all API requests and one of admin/operator/viewer should be used to assign the proper access level.

GET /config/rest/oauth-ccgrant/v1beta/AuthEntity HTTP/1.1
HOST: my-device
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "CCG_AuthzAdminClaim": "example-claim-admin",
        "CCG_AuthzOperatorClaim": "example-claim-operator",
        "CCG_AuthzViewerClaim": "example-claim-viewer",
        "CCG_OAuth2TokenVerify": "https://example.jwksverify.uri",
        "CCG_RequireClaim": "example-claim"
    }
}

Update a single setting​

All settings can be applied separately, such as changing the claim for admin access.

PATCH /config/rest/oauth-ccgrant/v1beta/AuthEntity/CCG_AuthzAdminClaim HTTP/1.1
HOST: my-device
Content-Type: application/json

{
    "data": "example-claim-admin"
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

API Definition​

Structure​

oauth-ccgrant.v1 (Root Entity)
    ├── AuthEntity (Entity)
        ├── CCG_AuthzAdminClaim (Property)
        ├── CCG_AuthzOperatorClaim (Property)
        ├── CCG_AuthzViewerClaim (Property)
        ├── CCG_OAuth2TokenVerify (Property)
        ├── CCG_RequireClaim (Property)

Entities​

oauth-ccgrant.v1​

  • Description: CCG configuration.
  • Type: Singleton
  • Operations
    • Get
    • Set
      • Properties: AuthEntity
  • Attributes
    • Dynamic Support: No
Properties​

This entity has no properties.

Actions​

This entity has no actions.

oauth-ccgrant.v1.AuthEntity​

  • Description: Client authentication properties.
  • Type: Singleton
  • Operations
    • Get
    • Set
      • Properties: CCG_AuthzAdminClaim, CCG_AuthzOperatorClaim, CCG_AuthzViewerClaim, CCG_OAuth2TokenVerify, CCG_RequireClaim
  • Attributes
    • Dynamic Support: No
Properties​
CCG_AuthzAdminClaim​
  • Description: Claim and value corresponding to to admin access
  • Datatype: optional_claim_type
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
CCG_AuthzOperatorClaim​
  • Description: Claim and value corresponding to operator access
  • Datatype: optional_claim_type
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
CCG_AuthzViewerClaim​
  • Description: Claim and value corresponding to viewer access
  • Datatype: optional_claim_type
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
CCG_OAuth2TokenVerify​
  • Description: JWKS URI that serves the public keys.
  • Datatype: url_type
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
CCG_RequireClaim​
  • Description: Required claim.
  • Datatype: required_claim_type
  • Operations
    • Get (Permissions: admin)
    • Set (Permissions: admin)
  • Attributes
    • Nullable: No
    • Dynamic Support: No / Dynamic Enum: No / Dynamic Range: No
Actions​

This entity has no actions.

Data Types​

optional_claim_type​

  • Description: Optional claims.
  • Type: string
  • Maximum Length: 256
  • Pattern: ^.*$

required_claim_type​

  • Description: Mandatory claims.
  • Type: string
  • Minimum Length: 1
  • Maximum Length: 256
  • Pattern: ^.*$

url_type​

  • Description: URL type.
  • Type: string
  • Minimum Length: 1
  • Maximum Length: 256
  • Pattern: ^[\\w "'.:\\-\\/\\/~?]+$
Last updated on