API Security Vocabulary: Authentication, Authorization, and Beyond

API security discussions are filled with abbreviations and concepts that are easy to confuse — authentication vs authorisation, OAuth flows, JWT structure. If you are reviewing a security design, writing a threat model, or explaining a vulnerability to a colleague, precise vocabulary prevents costly misunderstandings. This post covers the terms you encounter most often in real API security work.

Identity: Authentication vs Authorisation

Authentication (often abbreviated AuthN) — Verifying who the caller is. Phrase: “The API authenticates callers using API keys — each key is linked to a specific client application.”

Authorisation (often abbreviated AuthZ) — Determining what an authenticated caller is allowed to do. Phrase: “Authentication passed, but authorisation failed — the user doesn’t have the admin scope required to access this endpoint.”

A common confusion: “The API returned 401 Unauthorized” — but 401 actually means unauthenticated (no valid credentials). 403 Forbidden means unauthorised (valid credentials, insufficient permissions). This distinction matters in incident reports and API design reviews.

OAuth 2.0 and PKCE

OAuth 2.0 — An authorisation framework that allows third-party applications to obtain limited access to a resource on behalf of a user. OAuth defines several flows (also called grant types) for different use cases.

OAuth 2.0 flows — The main flows:

• Authorization Code — for server-side web apps; most secure
• Authorization Code + PKCE — for public clients (SPAs, mobile apps) where a client secret can’t be kept confidential
• Client Credentials — for machine-to-machine (M2M) authentication; no user involved
• Device Authorization — for devices with limited input capability (smart TVs, CLI tools)

Phrase: “We use the Client Credentials flow for the data pipeline — it’s a backend service with no user context.”

PKCE (Proof Key for Code Exchange) (pronunciation: “pixie”) — An extension to the Authorization Code flow that protects against interception attacks by using a code verifier and code challenge. Required for public clients. Phrase: “The mobile app uses PKCE — it generates a code verifier locally and sends only the hashed challenge to the authorisation server.”

Tokens and Signing

JWT (JSON Web Token) (pronunciation: “jot”) — A compact, self-contained token format. A JWT has three Base64URL-encoded parts separated by dots: header, payload, and signature. Phrase: “Decode the JWT payload on jwt.io to inspect the claims — but never trust the payload without verifying the signature.”

Claims — The key-value pairs in a JWT payload describing the token’s subject, issuer, expiry, and custom data (e.g. sub, iss, exp, scope). Phrase: “The JWT has a custom claim tenant_id — the API uses it to route requests to the correct database shard.”

HMAC (Hash-based Message Authentication Code) — A symmetric signing algorithm used to sign JWTs (HS256) or validate webhook payloads. Both parties share the same secret key. Phrase: “Webhook payloads are signed with HMAC-SHA256 — verify the signature before processing.”

API key — A simple secret string passed in a request header or query parameter to authenticate an API client. Simpler than OAuth but offers less granularity. Phrase: “Rotate the API key immediately — it was accidentally committed to the public repository.”

mTLS (Mutual TLS) — Both client and server present certificates to authenticate each other. Common in service-to-service communication within a service mesh. Phrase: “mTLS is enforced between internal services — no service can call another without a valid client certificate.”

Common Vulnerabilities and Defences

CORS (Cross-Origin Resource Sharing) — A browser security mechanism that restricts which origins can make cross-origin requests. Misconfigured CORS (e.g. Access-Control-Allow-Origin: * on an authenticated API) is a common vulnerability. Phrase: “The CORS policy only allows requests from our production domain — wildcard origins are never permitted on authenticated endpoints.”

CSRF (Cross-Site Request Forgery) — An attack that tricks a user’s browser into making an authenticated request to your API. Mitigated by CSRF tokens, SameSite cookies, and checking the Origin header.

Injection prevention — Validating and sanitising all API inputs to prevent SQL injection, command injection, and similar attacks. Phrase: “Use parameterised queries — never interpolate user input directly into SQL.”

Rate limiting — Restricting the number of requests per client per time window to prevent abuse and brute-force attacks.

API gateway security — Centralising authentication, authorisation, rate limiting, and input validation at the gateway layer rather than in each service.

OWASP API Security Top 10 — A widely cited list of the most critical API security risks, including Broken Object Level Authorisation (BOLA), Broken Authentication, Excessive Data Exposure, and Mass Assignment. Phrase: “The security review checklist is based on the OWASP API Security Top 10 — BOLA is the most common finding.”

Practice: Read the OWASP API Security Top 10 (owasp.org/www-project-api-security/) and write a one-sentence definition of each risk in your own words. Then compare with a colleague — differences reveal gaps in understanding.

Navigating Nuances: A Practical Approach to Security Conversations

Let’s be honest – discussing API security can feel…technical. And when you’re trying to explain complex concepts like authorization or authentication, it’s easy for things to get lost in jargon. One of the biggest challenges for non-native English speakers is not just understanding what is being said, but also how it’s being said – the subtle nuances that impact clarity and effectiveness. Let’s address how these concepts are often discussed in a professional setting, particularly when dealing with potential issues or requesting changes.

For example, imagine you’re reviewing a pull request for a new user authentication endpoint. The developer has implemented JWT (JSON Web Tokens) but hasn’t explicitly defined the scope of permissions granted to each token. A helpful comment you might leave isn’t simply “JWT needs scope.” Instead, you could say: “This implementation is good, but let’s clarify the scopes associated with these JWTs. We need to ensure users only have access to the resources they actually require – a ‘least privilege’ approach. Could we add comments to the code detailing exactly which API endpoints each JWT will be authorized for? This will greatly aid in understanding and auditing future changes.” Similarly, within Slack channels dedicated to API development, you might hear someone saying, “The server’s responding with a 403 Forbidden error – it looks like authorization is failing. We need to investigate whether the user’s credentials are valid and if they have the correct permissions for this specific action.” It’s about precision and explicitly stating the problem in terms of access control.

Another common scenario involves describing a change request. Instead of just saying “update CORS,” you would phrase it as, “We need to refine the CORS configuration to strictly limit which domains can access our API. Currently, any domain can make requests – this poses a significant risk. We should implement a whitelist approach, only allowing requests from known and trusted origins.” This level of detail is crucial when communicating with stakeholders who might not have a deep understanding of the underlying security mechanisms.

Furthermore, it’s important to remember that documentation isn’t just about listing definitions; it’s about providing context. A well-written API specification will clearly articulate why certain decisions were made regarding authentication and authorization – for example, explaining why PKCE (Proof Key for Code Exchange) was chosen over other methods for a mobile app login flow.

Here’s an example of how you might use curl to verify access after configuring CORS:

curl -H "Origin: https://example.com" https://api.example.org/users

This command demonstrates testing the configured CORS policy – ensuring that requests originating from https://example.com are permitted, while others might be blocked. Understanding these practical examples will help you confidently navigate security discussions and contribute effectively to API development projects.