API Access Authorisation Options

ManagementStudio provides several ways to authenticate when using the PowerShell API. These options vary in security, complexity, and suitability for automation.

To create any API token or certificate, your account must have the “Create API Tokens / Certs” role.

Overview of Authentication Methods

Username / Password

This method authenticates using the username and password of a ManagementStudio user account.

Industry term:
Basic credentials – Direct authentication using a username and password, without an intermediate token.

Warning: This method is not recommended because it exposes full account credentials and is difficult to audit or revoke safely.

Example

Connect-MSApi -ApiUrl "http://.." -ProjectId 1 -UserName "MyUserName" -Password "MyPassword"

Pros

• Simple to understand
• No token setup required

Cons

• Least secure option
• Exposes full account credentials
• Not suitable for production or automation

JWT Token (JSON Web Token)

A JSON Web Token (JWT) is a signed token that proves the identity of a user without exposing their password.

Industry term:
JWT – A compact, signed token containing identity and expiry information that can be verified by the server.

Creating a JWT Token

1. Select the user account in ManagementStudio
2. Right-click and select API Tokens → Create API JWT Token
3. Optionally change the expiry date (default: 90 days)
4. Click Create API JWT Token
5. Copy the token immediately (it is shown only once)

Example

Connect-MSApi -ApiUrl "http://.." -ProjectId 1 -Token "Bearer tokenValue"

Pros

• Industry-standard authentication
• Password is never exposed
• Easy to use in scripts

Cons

• Token expires and must be recreated
• No automatic renewal

Refresh Token

A Refresh Token extends JWT authentication by allowing short-lived access tokens to be renewed automatically.

Industry term:
Refresh token – A long-lived credential that can generate new short-lived access tokens.

Creating a Refresh Token

1. Select the user account
2. Right-click and select API Tokens → Create API Refresh Token
3. Optionally configure:
   • Token expiry (default: 90 days)
   • Access token duration (default: 3 hours)
4. Click Create API Refresh Token
5. Copy and securely store the token (shown once only)

Revoking a Refresh Token

Select the account and choose API Tokens → Revoke API Refresh Token.

Example

Connect-MSApi -ApiUrl "http://.." -ProjectId 1 -RefreshToken "tokenValue"

Pros

• Ideal for long-running or unattended scripts
• Access tokens rotate automatically
• Can be revoked without changing user passwords

Certificate Authentication

Certificate authentication allows ManagementStudio to trust API calls coming from a specific machine and user combination.

Industry terms:
Certificate – A cryptographic identity used to prove trust.
Thumbprint – A unique hash that identifies a certificate.

Rules

• Each account can have only one certificate
• A certificate can be used by only one account
• Certificates can be revoked at any time

Uploading a Certificate

1. Create a local certificate
2. Select the user account
3. Right-click and select API Certificate Auth → Upload Auth Certificate

Revoking a Certificate

Select the account and choose API Certificate Auth → Revoke Auth Certificate.

Examples

Connect-MSApi -ApiUrl "http://.." -ProjectId 1 -CertPath "c:\certs\MyMsCert.cer"

Connect-MSApi -ApiUrl "http://.." -ProjectId 1 -CertThumbprint "ABCDEF..."

Pros

• Highest level of security
• No passwords or tokens stored in scripts
• Ideal for production servers and CI/CD pipelines

Cons

• Requires certificate management
• More complex initial setup

Creating a Local Certificate (PowerShell)

$certname = "ManagementStudio API Auth Certificate"

$cert = New-SelfSignedCertificate `
  -Subject "CN=$certname" `
  -CertStoreLocation "Cert:\CurrentUser\My" `
  -KeyExportPolicy Exportable `
  -NotAfter (Get-Date).AddYears(2) `
  -KeyLength 2048 `
  -HashAlgorithm SHA256 `
  -KeySpec Signature `
  -Provider "Microsoft Enhanced RSA and AES Cryptographic Provider"

Export-Certificate `
  -Cert $cert `
  -FilePath "$env:USERPROFILE\Desktop\$certname.cer"

Recommendation

• Local testing: JWT Token
• Scheduled scripts / automation: Refresh Token
• Production servers & CI/CD: Certificate authentication
• Username / Password: Avoid except for temporary testing